perf: Eliminate double-fetching in semantic search sampling

Performance optimization that removes redundant verification step and
makes content fetching parallel in nc_semantic_search_answer tool.

Changes:
- Remove verification.py module (only had 1 caller)
- Refactor nc_semantic_search to do inline deduplication instead of
  calling verify_search_results()
- Migrate verification patterns (anyio task group, semaphore limiting)
  to nc_semantic_search_answer's content fetching
- Change content fetching from sequential loop to parallel execution

Performance impact:
- Before: 10 API calls (5 parallel verification + 5 sequential content)
  = ~5.5s overhead
- After: 5 API calls (parallel content fetch) = ~0.5s overhead
- Result: 50% fewer API calls, ~10x faster for sampling operations

Technical details:
- Uses anyio.create_task_group() for structured concurrency
- Semaphore limiting (max_concurrent=20) prevents connection pool exhaustion
- Index-based storage maintains result ordering
- Expected failures (deleted notes) logged at debug level
- Deduplication handles hybrid search returning same doc from dense + sparse

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

.github/workflows/bump-version.yml

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

.github/workflows/helm-release.yml

@@ -24,6 +24,18 @@ jobs:
           git config user.name "$GITHUB_ACTOR"
           git config user.email "$GITHUB_ACTOR@users.noreply.github.com"
 
+      - name: Install Helm
+        uses: azure/setup-helm@1a275c3b69536ee54be43f2070a358922e12c8d4 # v4.3.1
+        with:
+          version: v3.16.0
+
+      - name: Add Helm repositories and update dependencies
+        run: |
+          helm repo add qdrant https://qdrant.github.io/qdrant-helm
+          helm repo add ollama https://otwld.github.io/ollama-helm
+          helm repo update
+          helm dependency build charts/nextcloud-mcp-server
+
       - name: Run chart-releaser
         uses: helm/chart-releaser-action@cae68fefc6b5f367a0275617c9f83181ba54714f # v1.7.0
         env:

.github/workflows/release.yml

@@ -20,7 +20,7 @@ jobs:
       - name: Checkout
         uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5
       - name: Install uv
-        uses: astral-sh/setup-uv@85856786d1ce8acfbcc2f13a5f3fbd6b938f9f41 # v7.1.2
+        uses: astral-sh/setup-uv@5a7eac68fb9809dea845d802897dc5c723910fa3 # v7.1.3
       - name: Install Python 3.11
         run: uv python install 3.11
       - name: Build

.github/workflows/test.yml

@@ -11,7 +11,7 @@ jobs:
     steps:
       - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
       - name: Install the latest version of uv
-        uses: astral-sh/setup-uv@85856786d1ce8acfbcc2f13a5f3fbd6b938f9f41 # v7.1.2
+        uses: astral-sh/setup-uv@5a7eac68fb9809dea845d802897dc5c723910fa3 # v7.1.3
       - name: Check format
         run: |
           uv run --frozen ruff format --diff
@@ -52,10 +52,11 @@ 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
-        uses: astral-sh/setup-uv@85856786d1ce8acfbcc2f13a5f3fbd6b938f9f41 # v7.1.2
+        uses: astral-sh/setup-uv@5a7eac68fb9809dea845d802897dc5c723910fa3 # v7.1.3
 
       - name: Install Playwright dependencies
         run: |
@@ -84,4 +85,4 @@ jobs:
           NEXTCLOUD_USERNAME: "admin"
           NEXTCLOUD_PASSWORD: "admin"
         run: |
-          uv run pytest -v --log-cli-level=WARN --ignore=tests/manual
+          uv run pytest -v --log-cli-level=WARN -m smoke

.gitignore

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

CHANGELOG.md

@@ -1,3 +1,175 @@
+## v0.35.0 (2025-11-15)
+
+### Feat
+
+- Enable SSE transport for mcp service and update test fixtures
+
+## v0.34.2 (2025-11-13)
+
+### Fix
+
+- Use NEXTCLOUD_OIDC_CLIENT_ID/SECRET env vars consistently
+
+## v0.34.1 (2025-11-13)
+
+### Fix
+
+- return all notes when search query is empty
+
+## v0.34.0 (2025-11-13)
+
+### Feat
+
+- Complete Phase 5 - Instrument all 93 MCP tools
+- Add instrumentation decorator and apply to notes tools (Phase 5)
+- Add OAuth token and database metrics (Phases 3-4)
+- Add metrics instrumentation for queue, health, and database operations
+
+## v0.33.1 (2025-11-13)
+
+### Fix
+
+- Move grafana_folder from labels to annotations
+
+## v0.33.0 (2025-11-13)
+
+### Feat
+
+- Add Grafana dashboard and vector sync metric instrumentation
+
+## v0.32.1 (2025-11-12)
+
+### Fix
+
+- add dynamic dimension detection for Ollama embedding models
+
+## v0.32.0 (2025-11-11)
+
+### Feat
+
+- **ollama**: Pull model on startup if not available in ollama
+- add dynamic vector sync status updates with htmx polling
+- add webhook management UI and BeforeNodeDeletedEvent support
+- validate Nextcloud webhook schemas and document findings
+
+### Fix
+
+- improve webapp tab UI with CSS Grid and viewport-filling container
+
+### Refactor
+
+- move webapp from /user/page to /app
+- consolidate database storage for webhooks and OAuth tokens
+
+## v0.31.1 (2025-11-10)
+
+### Refactor
+
+- simplify OpenTelemetry tracing configuration
+
+## v0.31.0 (2025-11-10)
+
+### Feat
+
+- skip tracing for health and metrics endpoints
+
+### Fix
+
+- add retry logic for ETag conflicts in category change test
+- optimize Notes API pagination with pruneBefore parameter
+
+## v0.30.0 (2025-11-10)
+
+### Feat
+
+- **helm**: Add document chunking configuration
+- **vector**: Add configurable chunk size and overlap for document embedding
+- **vector**: Support multiple embedding models with auto-generated collection names
+
+### Fix
+
+- Support in-memory Qdrant for CI testing
+
+## v0.29.2 (2025-11-09)
+
+### Fix
+
+- **helm**: Set default strategy to Recreate
+
+## v0.29.1 (2025-11-09)
+
+### Fix
+
+- **observability**: isolate metrics endpoint to dedicated port
+
+## v0.29.0 (2025-11-09)
+
+### Feat
+
+- **helm**: Add observability support with ServiceMonitor and Grafana dashboard
+
+### Fix
+
+- **readiness**: Only check external Qdrant in network mode
+
+## v0.28.0 (2025-11-09)
+
+### Feat
+
+- **observability**: Add comprehensive monitoring with Prometheus and OpenTelemetry
+
+### Fix
+
+- **vector**: Handle missing 'modified' field in notes gracefully
+
+## v0.27.3 (2025-11-09)
+
+### Fix
+
+- **ci**: Use helm dependency build instead of update to use Chart.lock
+
+## v0.27.2 (2025-11-09)
+
+### Fix
+
+- **helm**: update Qdrant dependency condition to match new mode structure
+
+## v0.27.1 (2025-11-09)
+
+### Fix
+
+- **ci**: add Helm repository setup to chart release workflow
+
+## v0.27.0 (2025-11-09)
+
+### Feat
+
+- **helm**: add Qdrant local mode support with three deployment options [skip ci]
+- add Qdrant local mode support with in-memory and persistent storage
+- implement ADR-009 - refactor semantic search to use generic semantic:read scope
+- implement MCP sampling for semantic search RAG (ADR-008)
+- add optional vector database and semantic search to helm chart
+- add vector sync processing status to /app endpoint
+- implement semantic search tool and fix vector sync issues (ADR-007 Phase 3)
+- implement vector sync scanner and processor (ADR-007 Phase 2)
+
+### Fix
+
+- implement deletion grace period and vector sync status tool
+- remove unnecessary urllib3<2.0 constraint
+- integrate vector sync tasks with Starlette lifespan for streamable-http
+
+### Refactor
+
+- migrate vector sync from asyncio.Queue to anyio memory object streams
+- update to Qdrant query_points API and fix Playwright Keycloak login
+
+## v0.26.1 (2025-11-08)
+
+### Fix
+
+- **deps**: update dependency mcp to >=1.21,<1.22
+
 ## v0.26.0 (2025-11-08)
 
 ### Feat

CLAUDE.md

@@ -5,11 +5,13 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 ## Coding Conventions
 
 ### async/await Patterns
-- **Use anyio + asyncio hybrid** - Both libraries are available
+- **Use anyio for all async operations** - Provides structured concurrency
   - pytest runs in `anyio` mode (`anyio_mode = "auto"` in pyproject.toml)
-  - asyncio used in auth modules (refresh_token_storage.py, token_exchange.py, token_broker.py)
-  - anyio used in calendar.py, client_registration.py, app.py
+  - Use `anyio.create_task_group()` for concurrent execution (NOT `asyncio.gather()`)
+  - Use `anyio.Lock()` for synchronization primitives (NOT `asyncio.Lock()`)
+  - Use `anyio.run()` for entry points (NOT `asyncio.run()`)
   - Prefer standard async/await syntax without explicit library imports when possible
+  - Examples: app.py, search/hybrid.py, search/verification.py, auth/token_broker.py
 
 ### Type Hints
 - **Use Python 3.10+ union syntax**: `str | None` instead of `Optional[str]`
@@ -224,6 +226,82 @@ docker compose exec db mariadb -u root -ppassword nextcloud -e \
 
 **Testing**: Extract `data["results"]` from MCP responses, not `data` directly.
 
+## MCP Sampling for RAG (ADR-008)
+
+**What is MCP Sampling?**
+MCP sampling allows servers to request LLM completions from their clients. This enables Retrieval-Augmented Generation (RAG) patterns where the server retrieves context and the client's LLM generates answers.
+
+**When to use sampling:**
+- Generating natural language answers from retrieved documents
+- Synthesizing information from multiple sources
+- Creating summaries with citations
+
+**Implementation Pattern** (see ADR-008 for details):
+
+```python
+from mcp.types import ModelHint, ModelPreferences, SamplingMessage, TextContent
+
+@mcp.tool()
+@require_scopes("notes:read")
+async def nc_notes_semantic_search_answer(
+    query: str, ctx: Context, limit: int = 5, max_answer_tokens: int = 500
+) -> SamplingSearchResponse:
+    # 1. Retrieve documents
+    search_response = await nc_notes_semantic_search(query, ctx, limit)
+
+    # 2. Check for no results (don't waste sampling call)
+    if not search_response.results:
+        return SamplingSearchResponse(
+            query=query,
+            generated_answer="No relevant documents found.",
+            sources=[], total_found=0, success=True
+        )
+
+    # 3. Construct prompt with retrieved context
+    prompt = f"{query}\n\nDocuments:\n{format_sources(search_response.results)}\n\nProvide answer with citations."
+
+    # 4. Request LLM completion via sampling
+    try:
+        result = await ctx.session.create_message(
+            messages=[SamplingMessage(role="user", content=TextContent(type="text", text=prompt))],
+            max_tokens=max_answer_tokens,
+            temperature=0.7,
+            model_preferences=ModelPreferences(
+                hints=[ModelHint(name="claude-3-5-sonnet")],
+                intelligencePriority=0.8,
+                speedPriority=0.5,
+            ),
+            include_context="thisServer",
+        )
+
+        return SamplingSearchResponse(
+            query=query,
+            generated_answer=result.content.text,
+            sources=search_response.results,
+            model_used=result.model,
+            stop_reason=result.stopReason,
+            success=True
+        )
+    except Exception as e:
+        # Fallback: Return documents without generated answer
+        return SamplingSearchResponse(
+            query=query,
+            generated_answer=f"[Sampling unavailable: {e}]\n\nFound {len(search_response.results)} documents.",
+            sources=search_response.results,
+            search_method="semantic_sampling_fallback",
+            success=True
+        )
+```
+
+**Key Points**:
+- **No server-side LLM**: Server has no API keys, client controls which model is used
+- **Graceful degradation**: Tool always returns useful results even if sampling fails
+- **User control**: MCP clients SHOULD prompt users to approve sampling requests
+- **No results optimization**: Skip sampling call when no documents found
+- **Fixed prompts**: Prompts are not user-configurable to avoid injection risks
+
+**Reference**: See `nc_notes_semantic_search_answer` in `nextcloud_mcp_server/server/notes.py:517` and ADR-008 for complete implementation.
+
 ## Testing Best Practices (MANDATORY)
 
 ### Always Run Tests
@@ -315,3 +393,7 @@ 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

Dockerfile

@@ -1,4 +1,4 @@
-FROM ghcr.io/astral-sh/uv:0.9.8-python3.11-alpine@sha256:6c842c49ad032f46b62f32a7e7779f45f12671a8e0d82ea24c766ab62d58b396
+FROM ghcr.io/astral-sh/uv:0.9.9-python3.11-alpine@sha256:0faa7934fac1db7f5056f159c1224d144bab864fd2677a4066d25a686ae32edd
 
 # Install dependencies
 # 1. git (required for caldav dependency from git)
@@ -9,8 +9,9 @@ WORKDIR /app
 
 COPY . .
 
-RUN uv sync --locked --no-dev
+RUN uv sync --locked --no-dev --no-editable
 
 ENV PYTHONUNBUFFERED=1
+ENV VIRTUAL_ENV=/app/.venv
 
 ENTRYPOINT ["/app/.venv/bin/nextcloud-mcp-server", "--host", "0.0.0.0"]

README.md

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

charts/nextcloud-mcp-server/.gitignore

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

charts/nextcloud-mcp-server/Chart.lock

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

charts/nextcloud-mcp-server/Chart.yaml

@@ -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.26.0
-appVersion: "0.26.0"
+version: 0.35.0
+appVersion: "0.35.0"
 keywords:
   - nextcloud
   - mcp
@@ -21,3 +21,16 @@ home: https://github.com/cbcoutinho/nextcloud-mcp-server
 sources:
   - https://github.com/cbcoutinho/nextcloud-mcp-server
 icon: https://raw.githubusercontent.com/nextcloud/server/master/core/img/logo/logo.svg
+annotations:
+  # Grafana dashboard support
+  grafana_dashboard: "true"
+  grafana_dashboard_folder: "Nextcloud MCP"
+dependencies:
+  - name: qdrant
+    version: "1.15.5"
+    repository: https://qdrant.github.io/qdrant-helm
+    condition: qdrant.networkMode.deploySubchart
+  - name: ollama
+    version: "1.34.0"
+    repository: https://otwld.github.io/ollama-helm
+    condition: ollama.enabled

charts/nextcloud-mcp-server/README.md

@@ -14,8 +14,12 @@ This Helm chart deploys the Nextcloud MCP (Model Context Protocol) Server on a K
 ### Quick Start with Basic Authentication
 
 ```bash
+# Add the Helm repository
+helm repo add nextcloud-mcp https://cbcoutinho.github.io/nextcloud-mcp-server
+helm repo update
+
 # Install with basic auth (recommended for most users)
-helm install nextcloud-mcp ./helm/nextcloud-mcp-server \
+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
@@ -47,7 +51,7 @@ resources:
 Install with your custom values:
 
 ```bash
-helm install nextcloud-mcp ./helm/nextcloud-mcp-server -f custom-values.yaml
+helm install nextcloud-mcp nextcloud-mcp/nextcloud-mcp-server -f custom-values.yaml
 ```
 
 ### OAuth Authentication Mode (Experimental)
@@ -202,6 +206,146 @@ The application exposes HTTP health check endpoints:
 | `documentProcessing.unstructured.apiUrl` | Unstructured API URL | `http://unstructured:8000` |
 | `documentProcessing.tesseract.enabled` | Enable Tesseract OCR | `false` |
 
+#### Vector Search & Semantic Capabilities (Optional)
+
+Enable semantic search capabilities by deploying a vector database (Qdrant) and embedding service (Ollama or OpenAI).
+
+**Vector Sync Configuration:**
+
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| `vectorSync.enabled` | Enable background vector synchronization | `false` |
+| `vectorSync.scanInterval` | Scan interval in seconds | `3600` |
+| `vectorSync.processorWorkers` | Number of concurrent processor workers | `3` |
+| `vectorSync.queueMaxSize` | Maximum queue size for pending documents | `10000` |
+
+**Document Chunking Configuration:**
+
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| `documentChunking.chunkSize` | Number of words per chunk for embedding | `512` |
+| `documentChunking.chunkOverlap` | Number of overlapping words between chunks | `50` |
+
+**Chunking Strategy:**
+- **Small chunks (256-384)**: Better precision for searches, more storage overhead
+- **Medium chunks (512-768)**: Balanced approach (recommended for most use cases)
+- **Large chunks (1024+)**: Better context preservation, less precise matching
+- **Overlap**: Should be 10-20% of chunk size to preserve context across boundaries
+
+**Qdrant Vector Database:**
+
+Qdrant is deployed as a subchart when `qdrant.enabled` is `true`. All configuration values are passed through to the [qdrant/qdrant](https://github.com/qdrant/qdrant-helm) chart.
+
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| `qdrant.enabled` | Deploy Qdrant as a subchart | `false` |
+| `qdrant.replicaCount` | Number of Qdrant replicas | `1` |
+| `qdrant.image.tag` | Qdrant version | `v1.12.5` |
+| `qdrant.apiKey` | Optional API key for authentication | `""` |
+| `qdrant.persistence.size` | Storage size for vector data | `10Gi` |
+| `qdrant.persistence.storageClass` | Storage class | `""` |
+| `qdrant.resources.requests.cpu` | CPU request | `200m` |
+| `qdrant.resources.requests.memory` | Memory request | `512Mi` |
+| `qdrant.resources.limits.cpu` | CPU limit | `1000m` |
+| `qdrant.resources.limits.memory` | Memory limit | `2Gi` |
+
+**Ollama Embedding Service:**
+
+Ollama is deployed as a subchart when `ollama.enabled` is `true`. All configuration values are passed through to the [ollama/ollama](https://github.com/otwld/ollama-helm) chart. Alternatively, set `ollama.url` to use an external Ollama instance.
+
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| `ollama.enabled` | Deploy Ollama as a subchart | `false` |
+| `ollama.url` | External Ollama URL (use with `enabled: false`) | `""` |
+| `ollama.embeddingModel` | Embedding model to use | `nomic-embed-text` |
+| `ollama.verifySsl` | Verify SSL certificates | `true` |
+| `ollama.replicaCount` | Number of Ollama replicas | `1` |
+| `ollama.ollama.models.pull` | Models to pull on startup | `["nomic-embed-text"]` |
+| `ollama.persistentVolume.enabled` | Enable persistent storage | `true` |
+| `ollama.persistentVolume.size` | Storage size for models | `20Gi` |
+| `ollama.resources.requests.cpu` | CPU request | `500m` |
+| `ollama.resources.requests.memory` | Memory request | `1Gi` |
+| `ollama.resources.limits.cpu` | CPU limit | `2000m` |
+| `ollama.resources.limits.memory` | Memory limit | `4Gi` |
+
+**OpenAI Embedding Provider (Alternative):**
+
+Use OpenAI or any OpenAI-compatible API instead of Ollama.
+
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| `openai.enabled` | Enable OpenAI embedding provider | `false` |
+| `openai.apiKey` | OpenAI API key | `""` |
+| `openai.existingSecret` | Use existing secret for API key | `""` |
+| `openai.secretKey` | Key in secret containing API key | `api-key` |
+| `openai.baseUrl` | Custom API endpoint (optional) | `""` |
+
+#### Observability & Monitoring
+
+The chart includes comprehensive observability features including Prometheus metrics, OpenTelemetry tracing, and Grafana dashboards.
+
+**Metrics Configuration:**
+
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| `observability.metrics.enabled` | Enable Prometheus metrics | `true` |
+| `observability.metrics.port` | Metrics port | `9090` |
+| `observability.metrics.path` | Metrics endpoint path | `/metrics` |
+
+**Tracing Configuration:**
+
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| `observability.tracing.enabled` | Enable OpenTelemetry tracing | `false` |
+| `observability.tracing.endpoint` | OTLP collector endpoint | `""` |
+| `observability.tracing.serviceName` | Service name in traces | `nextcloud-mcp-server` |
+| `observability.tracing.samplingRate` | Trace sampling rate (0.0-1.0) | `1.0` |
+
+**Logging Configuration:**
+
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| `observability.logging.format` | Log format (json or text) | `json` |
+| `observability.logging.level` | Log level | `INFO` |
+| `observability.logging.includeTraceContext` | Include trace IDs in logs | `true` |
+
+**ServiceMonitor (Prometheus Operator):**
+
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| `serviceMonitor.enabled` | Create ServiceMonitor resource | `false` |
+| `serviceMonitor.interval` | Scrape interval | `30s` |
+| `serviceMonitor.scrapeTimeout` | Scrape timeout | `10s` |
+| `serviceMonitor.labels` | Additional labels for ServiceMonitor | `{}` |
+
+**PrometheusRule (Prometheus Operator):**
+
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| `prometheusRule.enabled` | Create PrometheusRule with alert rules | `false` |
+| `prometheusRule.labels` | Additional labels for PrometheusRule | `{}` |
+
+**Grafana Dashboards:**
+
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| `dashboards.enabled` | Enable automatic dashboard provisioning | `false` |
+| `dashboards.grafanaFolder` | Grafana folder name for dashboards | `Nextcloud MCP` |
+| `dashboards.labels` | Additional labels for dashboard ConfigMap | `{}` |
+| `dashboards.annotations` | Additional annotations for dashboard ConfigMap | `{}` |
+
+When `dashboards.enabled` is `true`, a ConfigMap with the Grafana dashboard is created with the `grafana_dashboard: "1"` label. This enables automatic discovery by Grafana sidecar containers (commonly used with kube-prometheus-stack).
+
+The dashboard provides comprehensive monitoring including:
+- HTTP request metrics (RED pattern: Rate, Errors, Duration)
+- MCP tool performance and errors
+- Nextcloud API performance by app (notes, calendar, contacts, etc.)
+- OAuth token operations and cache hit rates
+- External dependency health (Nextcloud, Qdrant, Keycloak, Unstructured API)
+- Vector sync processing pipeline (when enabled)
+
+For manual import or more details, see `charts/nextcloud-mcp-server/dashboards/README.md`.
+
 ## Examples
 
 ### Example 1: Basic Auth with Ingress
@@ -379,18 +523,106 @@ affinity:
           topologyKey: kubernetes.io/hostname
 ```
 
+### Example 5: Semantic Search with Qdrant and Ollama
+
+Deploy with vector search capabilities using embedded Qdrant and Ollama:
+
+```yaml
+nextcloud:
+  host: https://cloud.example.com
+
+auth:
+  mode: basic
+  basic:
+    username: admin
+    password: secure-password
+
+# Enable vector sync
+vectorSync:
+  enabled: true
+  scanInterval: 1800  # Scan every 30 minutes
+  processorWorkers: 5
+
+# Deploy Qdrant as a subchart
+qdrant:
+  enabled: true
+  persistence:
+    size: 20Gi
+    storageClass: fast-ssd
+  resources:
+    requests:
+      cpu: 500m
+      memory: 1Gi
+    limits:
+      cpu: 2000m
+      memory: 4Gi
+
+# Deploy Ollama as a subchart
+ollama:
+  enabled: true
+  embeddingModel: nomic-embed-text
+  persistentVolume:
+    size: 30Gi
+    storageClass: standard
+  resources:
+    requests:
+      cpu: 1000m
+      memory: 2Gi
+    limits:
+      cpu: 4000m
+      memory: 8Gi
+```
+
+Or use an external Ollama instance:
+
+```yaml
+vectorSync:
+  enabled: true
+
+qdrant:
+  enabled: true
+
+# Use external Ollama instead of deploying subchart
+ollama:
+  enabled: false
+  url: "http://ollama.ai-services.svc.cluster.local:11434"
+  embeddingModel: nomic-embed-text
+```
+
+Or use OpenAI for embeddings:
+
+```yaml
+vectorSync:
+  enabled: true
+
+qdrant:
+  enabled: true
+
+# Use OpenAI instead of Ollama
+openai:
+  enabled: true
+  apiKey: "sk-..."
+  # Or use existing secret:
+  # existingSecret: openai-api-key
+  # secretKey: api-key
+```
+
 ## Upgrading
 
 ### To upgrade an existing deployment:
 
 ```bash
-helm upgrade nextcloud-mcp ./helm/nextcloud-mcp-server -f custom-values.yaml
+# Update the repository
+helm repo update
+
+# Upgrade with your custom values
+helm upgrade nextcloud-mcp nextcloud-mcp/nextcloud-mcp-server -f custom-values.yaml
 ```
 
 ### To upgrade with new values:
 
 ```bash
-helm upgrade nextcloud-mcp ./helm/nextcloud-mcp-server \
+helm upgrade nextcloud-mcp nextcloud-mcp/nextcloud-mcp-server \
   --set resources.limits.memory=1Gi
 ```
 

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

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

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

@@ -69,6 +69,57 @@ Your Nextcloud MCP Server has been deployed in {{ .Values.auth.mode }} authentic
    {{- end }}
 {{- end }}
 
+{{- if .Values.vectorSync.enabled }}
+
+5. Vector Search & Semantic Capabilities:
+   - Vector Sync: Enabled
+   - Scan Interval: {{ .Values.vectorSync.scanInterval }}s
+   - Processor Workers: {{ .Values.vectorSync.processorWorkers }}
+   {{- if .Values.qdrant.enabled }}
+   - Qdrant: Deployed as subchart ({{ .Release.Name }}-qdrant:6333)
+   {{- else }}
+   - Qdrant: Not deployed (configure external instance)
+   {{- end }}
+   {{- if .Values.ollama.enabled }}
+   - Ollama: Deployed as subchart ({{ .Release.Name }}-ollama:11434)
+   - Embedding Model: {{ .Values.ollama.embeddingModel }}
+   {{- else if .Values.ollama.url }}
+   - Ollama: Using external instance at {{ .Values.ollama.url }}
+   - Embedding Model: {{ .Values.ollama.embeddingModel }}
+   {{- else if .Values.openai.enabled }}
+   - OpenAI: Enabled for embeddings
+   {{- else }}
+   - WARNING: No embedding provider configured (Ollama or OpenAI required)
+   {{- end }}
+
+   Check vector sync status:
+   kubectl --namespace {{ .Release.Namespace }} exec -it deploy/{{ include "nextcloud-mcp-server.fullname" . }} -- curl -s http://localhost:{{ include "nextcloud-mcp-server.port" . }}/user/page | grep "Vector Sync"
+{{- end }}
+
+{{- if .Values.dashboards.enabled }}
+
+6. Grafana Dashboards:
+   - Dashboard provisioning: Enabled
+   - ConfigMap: {{ include "nextcloud-mcp-server.fullname" . }}-dashboard
+   - Grafana Folder: {{ .Values.dashboards.grafanaFolder }}
+
+   The dashboard will be automatically imported by Grafana if the sidecar is configured
+   to watch for ConfigMaps with label "grafana_dashboard: 1".
+
+   To manually import the dashboard:
+   kubectl --namespace {{ .Release.Namespace }} get configmap {{ include "nextcloud-mcp-server.fullname" . }}-dashboard -o jsonpath='{.data.nextcloud-mcp-server\.json}' | jq . > dashboard.json
+
+   Then import dashboard.json via Grafana UI (Dashboards → Import).
+{{- else }}
+
+6. Grafana Dashboards:
+   - Dashboard provisioning: Disabled
+   - To enable automatic dashboard provisioning, set: dashboards.enabled=true
+
+   Manual import option:
+   The dashboard JSON is available in the chart at charts/nextcloud-mcp-server/dashboards/nextcloud-mcp-server.json
+{{- end }}
+
 For more information and documentation:
 - GitHub: https://github.com/cbcoutinho/nextcloud-mcp-server
 - Documentation: https://github.com/cbcoutinho/nextcloud-mcp-server#readme

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

@@ -94,6 +94,17 @@ Create the name of the PVC to use for OAuth storage
 {{- end }}
 {{- end }}
 
+{{/*
+Create the name of the PVC to use for Qdrant local persistent storage
+*/}}
+{{- define "nextcloud-mcp-server.qdrantPvcName" -}}
+{{- if .Values.qdrant.localPersistence.existingClaim }}
+{{- .Values.qdrant.localPersistence.existingClaim }}
+{{- else }}
+{{- include "nextcloud-mcp-server.fullname" . }}-qdrant-data
+{{- end }}
+{{- end }}
+
 {{/*
 Return the MCP server port
 */}}

charts/nextcloud-mcp-server/templates/dashboard-configmap.yaml

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

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

@@ -5,6 +5,8 @@ metadata:
   labels:
     {{- include "nextcloud-mcp-server.labels" . | nindent 4 }}
 spec:
+  strategy:
+    type: Recreate
   {{- if not .Values.autoscaling.enabled }}
   replicas: {{ .Values.replicaCount }}
   {{- end }}
@@ -56,6 +58,11 @@ spec:
             - name: http
               containerPort: {{ include "nextcloud-mcp-server.port" . }}
               protocol: TCP
+            {{- if .Values.observability.metrics.enabled }}
+            - name: metrics
+              containerPort: {{ .Values.observability.metrics.port }}
+              protocol: TCP
+            {{- end }}
           env:
             # Nextcloud connection
             - name: NEXTCLOUD_HOST
@@ -140,6 +147,90 @@ spec:
               value: {{ .Values.documentProcessing.custom.types | quote }}
             {{- end }}
             {{- end }}
+            # Vector Sync
+            - name: VECTOR_SYNC_ENABLED
+              value: {{ .Values.vectorSync.enabled | quote }}
+            {{- if .Values.vectorSync.enabled }}
+            - name: VECTOR_SYNC_SCAN_INTERVAL
+              value: {{ .Values.vectorSync.scanInterval | quote }}
+            - name: VECTOR_SYNC_PROCESSOR_WORKERS
+              value: {{ .Values.vectorSync.processorWorkers | quote }}
+            - name: VECTOR_SYNC_QUEUE_MAX_SIZE
+              value: {{ .Values.vectorSync.queueMaxSize | quote }}
+            {{- end }}
+            # Document Chunking (always set, used by vector sync processor)
+            - name: DOCUMENT_CHUNK_SIZE
+              value: {{ .Values.documentChunking.chunkSize | quote }}
+            - name: DOCUMENT_CHUNK_OVERLAP
+              value: {{ .Values.documentChunking.chunkOverlap | quote }}
+            # Qdrant Vector Database
+            {{- if eq .Values.qdrant.mode "network" }}
+            # Network mode: Use dedicated Qdrant service
+            {{- if .Values.qdrant.networkMode.deploySubchart }}
+            - name: QDRANT_URL
+              value: "http://{{ .Release.Name }}-qdrant:6333"
+            {{- else if .Values.qdrant.networkMode.externalUrl }}
+            - name: QDRANT_URL
+              value: {{ .Values.qdrant.networkMode.externalUrl | quote }}
+            {{- end }}
+            {{- if or .Values.qdrant.networkMode.apiKey .Values.qdrant.networkMode.existingSecret }}
+            - name: QDRANT_API_KEY
+              valueFrom:
+                secretKeyRef:
+                  name: {{ .Values.qdrant.networkMode.existingSecret | default (printf "%s-qdrant" .Release.Name) }}
+                  key: {{ .Values.qdrant.networkMode.secretKey }}
+            {{- end }}
+            {{- else if eq .Values.qdrant.mode "persistent" }}
+            # Persistent local mode: File-based storage
+            - name: QDRANT_LOCATION
+              value: {{ .Values.qdrant.localPersistence.dataPath | quote }}
+            {{- else }}
+            # In-memory mode (default): Ephemeral storage
+            - name: QDRANT_LOCATION
+              value: ":memory:"
+            {{- end }}
+            - name: QDRANT_COLLECTION
+              value: {{ .Values.qdrant.collection | quote }}
+            # Ollama Embedding Service
+            {{- if or .Values.ollama.enabled .Values.ollama.url }}
+            - name: OLLAMA_BASE_URL
+              value: {{ .Values.ollama.url | default (printf "http://%s-ollama:11434" .Release.Name) | quote }}
+            - name: OLLAMA_EMBEDDING_MODEL
+              value: {{ .Values.ollama.embeddingModel | quote }}
+            - name: OLLAMA_VERIFY_SSL
+              value: {{ .Values.ollama.verifySsl | quote }}
+            {{- end }}
+            # OpenAI Embedding Provider (alternative to Ollama)
+            {{- if .Values.openai.enabled }}
+            - name: OPENAI_API_KEY
+              valueFrom:
+                secretKeyRef:
+                  name: {{ .Values.openai.existingSecret | default (printf "%s-openai" (include "nextcloud-mcp-server.fullname" .)) }}
+                  key: {{ .Values.openai.secretKey }}
+            {{- if .Values.openai.baseUrl }}
+            - name: OPENAI_BASE_URL
+              value: {{ .Values.openai.baseUrl | quote }}
+            {{- end }}
+            {{- end }}
+            # Observability
+            - name: METRICS_ENABLED
+              value: {{ .Values.observability.metrics.enabled | quote }}
+            - name: METRICS_PORT
+              value: {{ .Values.observability.metrics.port | quote }}
+            {{- if .Values.observability.tracing.enabled }}
+            - name: OTEL_EXPORTER_OTLP_ENDPOINT
+              value: {{ .Values.observability.tracing.endpoint | quote }}
+            - name: OTEL_SERVICE_NAME
+              value: {{ .Values.observability.tracing.serviceName | quote }}
+            - name: OTEL_TRACES_SAMPLER_ARG
+              value: {{ .Values.observability.tracing.samplingRate | quote }}
+            {{- end }}
+            - name: LOG_FORMAT
+              value: {{ .Values.observability.logging.format | quote }}
+            - name: LOG_LEVEL
+              value: {{ .Values.observability.logging.level | quote }}
+            - name: LOG_INCLUDE_TRACE_CONTEXT
+              value: {{ .Values.observability.logging.includeTraceContext | quote }}
             {{- with .Values.extraEnv }}
             {{- toYaml . | nindent 12 }}
             {{- end }}
@@ -160,6 +251,10 @@ spec:
             - name: oauth-storage
               mountPath: /app/.oauth
             {{- end }}
+            {{- if and (eq .Values.qdrant.mode "persistent") .Values.qdrant.localPersistence.enabled }}
+            - name: qdrant-data
+              mountPath: /app/data
+            {{- end }}
             {{- with .Values.volumeMounts }}
             {{- toYaml . | nindent 12 }}
             {{- end }}
@@ -171,6 +266,11 @@ spec:
           persistentVolumeClaim:
             claimName: {{ include "nextcloud-mcp-server.oauthPvcName" . }}
         {{- end }}
+        {{- if and (eq .Values.qdrant.mode "persistent") .Values.qdrant.localPersistence.enabled }}
+        - name: qdrant-data
+          persistentVolumeClaim:
+            claimName: {{ include "nextcloud-mcp-server.qdrantPvcName" . }}
+        {{- end }}
         {{- with .Values.volumes }}
         {{- toYaml . | nindent 8 }}
         {{- end }}

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

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

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

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

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

@@ -15,3 +15,21 @@ spec:
     requests:
       storage: {{ .Values.auth.oauth.persistence.size }}
 {{- end }}
+---
+{{- if and (eq .Values.qdrant.mode "persistent") .Values.qdrant.localPersistence.enabled (not .Values.qdrant.localPersistence.existingClaim) }}
+apiVersion: v1
+kind: PersistentVolumeClaim
+metadata:
+  name: {{ include "nextcloud-mcp-server.fullname" . }}-qdrant-data
+  labels:
+    {{- include "nextcloud-mcp-server.labels" . | nindent 4 }}
+spec:
+  accessModes:
+    - {{ .Values.qdrant.localPersistence.accessMode }}
+  {{- if .Values.qdrant.localPersistence.storageClass }}
+  storageClassName: {{ .Values.qdrant.localPersistence.storageClass }}
+  {{- end }}
+  resources:
+    requests:
+      storage: {{ .Values.qdrant.localPersistence.size }}
+{{- end }}

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

@@ -15,5 +15,11 @@ spec:
       targetPort: http
       protocol: TCP
       name: http
+    {{- if .Values.observability.metrics.enabled }}
+    - port: {{ .Values.observability.metrics.port }}
+      targetPort: metrics
+      protocol: TCP
+      name: metrics
+    {{- end }}
   selector:
     {{- include "nextcloud-mcp-server.selectorLabels" . | nindent 4 }}

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

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

charts/nextcloud-mcp-server/values.yaml

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

docker-compose.yml

@@ -3,7 +3,7 @@ services:
   # https://hub.docker.com/_/mariadb
   db:
     # Note: Check the recommend version here: https://docs.nextcloud.com/server/latest/admin_manual/installation/system_requirements.html#server
-    image: docker.io/library/mariadb:lts@sha256:ae6119716edac6998ae85508431b3d2e666530ddf4e94c61a10710caec9b0f71
+    image: docker.io/library/mariadb:lts@sha256:6b848cb24fbbd87429917f6c4422ac53c343e85692eb0fef86553e99e4f422f3
     restart: always
     command: --transaction-isolation=READ-COMMITTED
     volumes:
@@ -34,7 +34,7 @@ services:
       - ./app-hooks:/docker-entrypoint-hooks.d:ro
       # Mount OIDC development directory outside /var/www/html to avoid rsync conflicts
       # The post-installation hook will register /opt/apps as an additional app directory
-      - ./third_party:/opt/apps:ro
+      #- ./third_party:/opt/apps:ro
     environment:
       - NEXTCLOUD_TRUSTED_DOMAINS=app
       - NEXTCLOUD_ADMIN_USER=admin
@@ -58,7 +58,7 @@ services:
       - ./tests/fixtures/nginx.conf:/etc/nginx/nginx.conf:ro
 
   unstructured:
-    image: downloads.unstructured.io/unstructured-io/unstructured-api:latest@sha256:a43ab55898599157fb0e0e097dabb8ecdd1d8e3df1ae5b67c6e15a136b171a6c
+    image: downloads.unstructured.io/unstructured-io/unstructured-api:latest@sha256:54282d3a25f33fd6cf69bc45b3d37770f213593f58b6dfe5e85fe546376b2807
     restart: always
     ports:
       - 127.0.0.1:8002:8000
@@ -69,17 +69,58 @@ services:
 
   mcp:
     build: .
-    command: ["--transport", "streamable-http"]
     restart: always
+    command: ["--transport", "streamable-http"]
     depends_on:
       app:
         condition: service_healthy
     ports:
       - 127.0.0.1:8000:8000
+      - 127.0.0.1:9090:9090
+    volumes:
+      - mcp-data:/app/data
     environment:
       - NEXTCLOUD_HOST=http://app:80
       - NEXTCLOUD_USERNAME=admin
       - NEXTCLOUD_PASSWORD=admin
+      - NEXTCLOUD_PUBLIC_ISSUER_URL=http://localhost:8080
+
+      # Vector sync configuration (ADR-007)
+      - VECTOR_SYNC_ENABLED=true
+      - VECTOR_SYNC_SCAN_INTERVAL=60
+      - VECTOR_SYNC_PROCESSOR_WORKERS=1
+
+      #- LOG_FORMAT=json
+
+      # Qdrant configuration (three modes):
+      # 1. Network mode: Set QDRANT_URL=http://qdrant:6333 (requires qdrant service)
+      # 2. In-memory mode: Set QDRANT_LOCATION=:memory: (default if nothing set)
+      # 3. Persistent local: Set QDRANT_LOCATION=/app/data/qdrant (stored in mcp-data volume)
+      #- QDRANT_LOCATION=/app/data/qdrant  # In-memory mode used if not set
+      #- QDRANT_URL=http://qdrant:6333  # Uncomment for network mode
+      #- QDRANT_API_KEY=${QDRANT_API_KEY:-my_secret_api_key}  # Only for network mode
+
+      # Observability
+      #- OTEL_SERVICE_NAME=nextcloud-mcp-docker-compose
+      #- OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4317
+
+      # Collection naming: Auto-generated as {deployment-id}-{model-name}
+      # - Deployment ID: OTEL_SERVICE_NAME (if set) or hostname (fallback)
+      # - Model name: OLLAMA_EMBEDDING_MODEL
+      # - Example: "nextcloud-mcp-server-nomic-embed-text"
+      # - Changing models creates new collection (requires re-embedding)
+      # - Set QDRANT_COLLECTION to override auto-generation:
+      #- QDRANT_COLLECTION=nextcloud_content
+
+      # Ollama configuration (optional - uses SimpleEmbeddingProvider if not set)
+      # - OLLAMA_BASE_URL=http://ollama:11434
+      # - OLLAMA_EMBEDDING_MODEL=nomic-embed-text  # Changing this creates new collection
+      # - OLLAMA_VERIFY_SSL=false
+
+      # Document chunking configuration (for vector embeddings)
+      # Tune these based on your embedding model and content type
+      # - DOCUMENT_CHUNK_SIZE=512      # Words per chunk (default: 512)
+      # - DOCUMENT_CHUNK_OVERLAP=50    # Overlapping words (default: 50, recommended: 10-20% of chunk size)
 
   mcp-oauth:
     build: .
@@ -117,7 +158,7 @@ services:
       - oauth-tokens:/app/data
 
   keycloak:
-    image: quay.io/keycloak/keycloak:26.4.4@sha256:c6459d5fae1b759f5d667ebdc6237ab3121379c3494e213898569014ede1846d
+    image: quay.io/keycloak/keycloak:26.4.5@sha256:653852bfdea2be6e958b9e90a976eff1c6de34edd55f2f679bdc48ef16bc528e
     command:
       - "start-dev"
       - "--import-realm"
@@ -154,8 +195,8 @@ services:
       # Provider auto-detected from OIDC_DISCOVERY_URL issuer
       # Using internal Docker hostname for discovery to get consistent issuer
       - OIDC_DISCOVERY_URL=http://keycloak:8080/realms/nextcloud-mcp/.well-known/openid-configuration
-      - OIDC_CLIENT_ID=nextcloud-mcp-server
-      - OIDC_CLIENT_SECRET=mcp-secret-change-in-production
+      - NEXTCLOUD_OIDC_CLIENT_ID=nextcloud-mcp-server
+      - NEXTCLOUD_OIDC_CLIENT_SECRET=mcp-secret-change-in-production
       - OIDC_JWKS_URI=http://keycloak:8080/realms/nextcloud-mcp/protocol/openid-connect/certs
 
       # Nextcloud API endpoint (for accessing APIs with validated token)
@@ -183,6 +224,24 @@ services:
       - keycloak-tokens:/app/data
       - keycloak-oauth-storage:/app/.oauth
 
+  qdrant:
+    image: qdrant/qdrant:v1.15.5@sha256:0fb8897412abc81d1c0430a899b9a81eb8328aa634e7242d1bc804c1fe8fe863
+    restart: always
+    ports:
+      - 127.0.0.1:6333:6333  # REST API
+      - 127.0.0.1:6334:6334  # gRPC (optional)
+    volumes:
+      - qdrant-data:/qdrant/storage
+    environment:
+      - QDRANT__SERVICE__API_KEY=${QDRANT_API_KEY:-my_secret_api_key}
+    healthcheck:
+      test: ["CMD-SHELL", "test -f /qdrant/.qdrant-initialized"]
+      interval: 10s
+      timeout: 5s
+      retries: 10
+    profiles:
+      - qdrant
+
 volumes:
   nextcloud:
   db:
@@ -190,3 +249,5 @@ volumes:
   oauth-tokens:
   keycloak-tokens:
   keycloak-oauth-storage:
+  qdrant-data:
+  mcp-data:

docs/ADR-003-vector-database-semantic-search.md

@@ -1,7 +1,9 @@
 # ADR-003: Vector Database and Semantic Search Architecture
 
 ## Status
-Proposed
+Superseded by ADR-007
+
+**Note**: This ADR was never implemented. The core technical decisions (Qdrant, embeddings, hybrid search) remain valid and are incorporated into ADR-007, which adds user-controlled background job management, task queuing, multi-user scheduling, and web UI integration. See [ADR-007: Background Vector Sync with User-Controlled Job Management](./ADR-007-background-vector-sync-job-management.md) for the implemented architecture.
 
 ## Context
 

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

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

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

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

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

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

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

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

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

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

docs/ADR-013-rag-evaluation.md

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

docs/configuration.md

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

docs/notes.md

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

docs/oauth-architecture.md

@@ -634,6 +634,12 @@ The server supports the following OAuth scopes, organized by Nextcloud app:
 - `sharing:read` - List shares and read share information
 - `sharing:write` - Create, update, and delete shares
 
+#### Semantic Search (Multi-App Vector Database)
+- `semantic:read` - Query vector database, perform semantic search across all indexed Nextcloud apps (notes, calendar, deck, files, contacts)
+- `semantic:write` - Enable/disable background vector synchronization, manage indexing settings
+
+> **Note**: Semantic search scopes provide access to the vector database that indexes content across **all** Nextcloud apps. Unlike app-specific scopes (e.g., `notes:read`), semantic scopes grant cross-app search capabilities powered by background vector synchronization (ADR-007).
+
 ### Scope Discovery
 
 The MCP server provides scope discovery through two mechanisms:

docs/observability.md

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

docs/semantic-search-architecture.md

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

env.sample

@@ -124,3 +124,75 @@ 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

nextcloud_mcp_server/app.py

@@ -1,23 +1,28 @@
 import logging
 import os
+import time
 from collections.abc import AsyncIterator
 from contextlib import AsyncExitStack, asynccontextmanager
 from dataclasses import dataclass
 from typing import TYPE_CHECKING, Optional
 
-if TYPE_CHECKING:
-    from nextcloud_mcp_server.auth.refresh_token_storage import RefreshTokenStorage
+from opentelemetry.instrumentation.httpx import HTTPXClientInstrumentor
 
+if TYPE_CHECKING:
+    from nextcloud_mcp_server.auth.storage import RefreshTokenStorage
+
+
+import anyio
 import click
 import httpx
-import uvicorn
+from anyio.streams.memory import MemoryObjectReceiveStream, MemoryObjectSendStream
 from mcp.server.auth.settings import AuthSettings
 from mcp.server.fastmcp import Context, FastMCP
 from pydantic import AnyHttpUrl
 from starlette.applications import Starlette
 from starlette.middleware.authentication import AuthenticationMiddleware
 from starlette.middleware.cors import CORSMiddleware
-from starlette.responses import JSONResponse
+from starlette.responses import JSONResponse, RedirectResponse
 from starlette.routing import Mount, Route
 
 from nextcloud_mcp_server.auth import (
@@ -30,25 +35,36 @@ from nextcloud_mcp_server.auth import (
 from nextcloud_mcp_server.auth.unified_verifier import UnifiedTokenVerifier
 from nextcloud_mcp_server.client import NextcloudClient
 from nextcloud_mcp_server.config import (
-    LOGGING_CONFIG,
     get_document_processor_config,
-    setup_logging,
+    get_settings,
 )
 from nextcloud_mcp_server.context import get_client as get_nextcloud_client
 from nextcloud_mcp_server.document_processors import get_registry
+from nextcloud_mcp_server.observability import (
+    ObservabilityMiddleware,
+    setup_metrics,
+    setup_tracing,
+)
+from nextcloud_mcp_server.observability.metrics import (
+    record_dependency_check,
+    set_dependency_health,
+)
 from nextcloud_mcp_server.server import (
     configure_calendar_tools,
     configure_contacts_tools,
     configure_cookbook_tools,
     configure_deck_tools,
     configure_notes_tools,
+    configure_semantic_tools,
     configure_sharing_tools,
     configure_tables_tools,
     configure_webdav_tools,
 )
 from nextcloud_mcp_server.server.oauth_tools import register_oauth_tools
+from nextcloud_mcp_server.vector import processor_task, scanner_task
 
 logger = logging.getLogger(__name__)
+HTTPXClientInstrumentor().instrument()
 
 
 def initialize_document_processors():
@@ -206,6 +222,11 @@ class AppContext:
     """Application context for BasicAuth mode."""
 
     client: NextcloudClient
+    storage: Optional["RefreshTokenStorage"] = None
+    document_send_stream: Optional[MemoryObjectSendStream] = None
+    document_receive_stream: Optional[MemoryObjectReceiveStream] = None
+    shutdown_event: Optional[anyio.Event] = None
+    scanner_wake_event: Optional[anyio.Event] = None
 
 
 @dataclass
@@ -275,7 +296,7 @@ async def load_oauth_client_credentials(
 
     # Try loading from SQLite storage
     try:
-        from nextcloud_mcp_server.auth.refresh_token_storage import RefreshTokenStorage
+        from nextcloud_mcp_server.auth.storage import RefreshTokenStorage
 
         storage = RefreshTokenStorage.from_env()
         await storage.initialize()
@@ -329,7 +350,7 @@ async def load_oauth_client_credentials(
 
         # Ensure OAuth client in SQLite storage
         from nextcloud_mcp_server.auth.client_registration import ensure_oauth_client
-        from nextcloud_mcp_server.auth.refresh_token_storage import RefreshTokenStorage
+        from nextcloud_mcp_server.auth.storage import RefreshTokenStorage
 
         storage = RefreshTokenStorage.from_env()
         await storage.initialize()
@@ -369,6 +390,9 @@ async def app_lifespan_basic(server: FastMCP) -> AsyncIterator[AppContext]:
 
     Creates a single Nextcloud client with basic authentication
     that is shared across all requests.
+
+    If vector sync is enabled (VECTOR_SYNC_ENABLED=true), also starts
+    background tasks for automatic document indexing (ADR-007).
     """
     logger.info("Starting MCP server in BasicAuth mode")
     logger.info("Creating Nextcloud client with BasicAuth")
@@ -376,14 +400,101 @@ async def app_lifespan_basic(server: FastMCP) -> AsyncIterator[AppContext]:
     client = NextcloudClient.from_env()
     logger.info("Client initialization complete")
 
+    # Initialize persistent storage (for webhook tracking and future features)
+    from nextcloud_mcp_server.auth.storage import RefreshTokenStorage
+
+    storage = RefreshTokenStorage.from_env()
+    await storage.initialize()
+    logger.info("Persistent storage initialized (webhook tracking enabled)")
+
     # Initialize document processors
     initialize_document_processors()
 
-    try:
-        yield AppContext(client=client)
-    finally:
-        logger.info("Shutting down BasicAuth mode")
-        await client.close()
+    settings = get_settings()
+
+    # Check if vector sync is enabled
+    if settings.vector_sync_enabled:
+        logger.info("Vector sync enabled - starting background tasks")
+
+        # Get username from environment for BasicAuth mode
+        username = os.getenv("NEXTCLOUD_USERNAME")
+        if not username:
+            raise ValueError(
+                "NEXTCLOUD_USERNAME is required for vector sync in BasicAuth mode"
+            )
+
+        # Initialize Qdrant collection before starting background tasks
+        logger.info("Initializing Qdrant collection...")
+        from nextcloud_mcp_server.vector.qdrant_client import get_qdrant_client
+
+        try:
+            await get_qdrant_client()  # Triggers collection creation if needed
+            logger.info("Qdrant collection ready")
+        except Exception as e:
+            logger.error(f"Failed to initialize Qdrant collection: {e}")
+            raise RuntimeError(
+                f"Cannot start vector sync - Qdrant initialization failed: {e}"
+            ) from e
+
+        # Initialize shared state
+        send_stream, receive_stream = anyio.create_memory_object_stream(
+            max_buffer_size=settings.vector_sync_queue_max_size
+        )
+        shutdown_event = anyio.Event()
+        scanner_wake_event = anyio.Event()
+
+        # Start background tasks using anyio TaskGroup
+        async with anyio.create_task_group() as tg:
+            # Start scanner task
+            await tg.start(
+                scanner_task,
+                send_stream,
+                shutdown_event,
+                scanner_wake_event,
+                client,
+                username,
+            )
+
+            # Start processor pool (each gets a cloned receive stream)
+            for i in range(settings.vector_sync_processor_workers):
+                await tg.start(
+                    processor_task,
+                    i,
+                    receive_stream.clone(),
+                    shutdown_event,
+                    client,
+                    username,
+                )
+
+            logger.info(
+                f"Background sync tasks started: 1 scanner + {settings.vector_sync_processor_workers} processors"
+            )
+
+            # Yield with background tasks running
+            try:
+                yield AppContext(
+                    client=client,
+                    storage=storage,
+                    document_send_stream=send_stream,
+                    document_receive_stream=receive_stream,
+                    shutdown_event=shutdown_event,
+                    scanner_wake_event=scanner_wake_event,
+                )
+            finally:
+                # Shutdown signal
+                logger.info("Shutting down background sync tasks")
+                shutdown_event.set()
+
+                # TaskGroup automatically cancels all tasks on exit
+                logger.info("Background sync tasks stopped")
+                await client.close()
+    else:
+        # No vector sync - simple lifecycle
+        try:
+            yield AppContext(client=client, storage=storage)
+        finally:
+            logger.info("Shutting down BasicAuth mode")
+            await client.close()
 
 
 async def setup_oauth_config():
@@ -396,9 +507,9 @@ async def setup_oauth_config():
     - External IdP mode: OIDC_DISCOVERY_URL points to external provider
       → External IdP for OAuth, Nextcloud user_oidc validates tokens and provides API access
 
-    Uses generic OIDC environment variables:
+    Uses OIDC environment variables:
     - OIDC_DISCOVERY_URL: OIDC discovery endpoint (optional, defaults to NEXTCLOUD_HOST)
-    - OIDC_CLIENT_ID / OIDC_CLIENT_SECRET: Static credentials (optional, uses DCR if not provided)
+    - NEXTCLOUD_OIDC_CLIENT_ID / NEXTCLOUD_OIDC_CLIENT_SECRET: Static credentials (optional, uses DCR if not provided)
     - NEXTCLOUD_OIDC_SCOPES: Requested OAuth scopes
 
     This is done synchronously before FastMCP initialization because FastMCP
@@ -497,7 +608,7 @@ async def setup_oauth_config():
     refresh_token_storage = None
     if enable_offline_access:
         try:
-            from nextcloud_mcp_server.auth.refresh_token_storage import (
+            from nextcloud_mcp_server.auth.storage import (
                 RefreshTokenStorage,
             )
 
@@ -522,19 +633,21 @@ async def setup_oauth_config():
             )
 
     # Load client credentials (static or dynamic registration)
-    client_id = os.getenv("OIDC_CLIENT_ID")
-    client_secret = os.getenv("OIDC_CLIENT_SECRET")
+    client_id = os.getenv("NEXTCLOUD_OIDC_CLIENT_ID")
+    client_secret = os.getenv("NEXTCLOUD_OIDC_CLIENT_SECRET")
 
     if client_id and client_secret:
         logger.info(f"Using static OIDC client credentials: {client_id}")
     elif registration_endpoint:
-        logger.info("OIDC_CLIENT_ID not set, attempting Dynamic Client Registration")
+        logger.info(
+            "NEXTCLOUD_OIDC_CLIENT_ID not set, attempting Dynamic Client Registration"
+        )
         client_id, client_secret = await load_oauth_client_credentials(
             nextcloud_host=nextcloud_host, registration_endpoint=registration_endpoint
         )
     else:
         raise ValueError(
-            "OIDC_CLIENT_ID and OIDC_CLIENT_SECRET environment variables are required "
+            "NEXTCLOUD_OIDC_CLIENT_ID and NEXTCLOUD_OIDC_CLIENT_SECRET environment variables are required "
             "when the OIDC provider does not support Dynamic Client Registration. "
             f"Discovery URL: {discovery_url}"
         )
@@ -698,7 +811,31 @@ async def setup_oauth_config():
 
 
 def get_app(transport: str = "sse", enabled_apps: list[str] | None = None):
-    setup_logging()
+    # Initialize observability (logging will be configured by uvicorn)
+    settings = get_settings()
+
+    # Setup Prometheus metrics (always enabled by default)
+    if settings.metrics_enabled:
+        setup_metrics(port=settings.metrics_port)
+        logger.info(
+            f"Prometheus metrics enabled on dedicated port {settings.metrics_port}"
+        )
+
+    # Setup OpenTelemetry tracing (optional)
+    if settings.otel_exporter_otlp_endpoint:
+        setup_tracing(
+            service_name=settings.otel_service_name,
+            otlp_endpoint=settings.otel_exporter_otlp_endpoint,
+            otlp_verify_ssl=settings.otel_exporter_verify_ssl,
+            sampling_rate=settings.otel_traces_sampler_arg,
+        )
+        logger.info(
+            f"OpenTelemetry tracing enabled (endpoint: {settings.otel_exporter_otlp_endpoint})"
+        )
+    else:
+        logger.info(
+            "OpenTelemetry tracing disabled (set OTEL_EXPORTER_OTLP_ENDPOINT to enable)"
+        )
 
     # Determine authentication mode
     oauth_enabled = is_oauth_mode()
@@ -798,6 +935,14 @@ def get_app(transport: str = "sse", enabled_apps: list[str] | None = None):
                 f"Unknown app: {app_name}. Available apps: {list(available_apps.keys())}"
             )
 
+    # Register semantic search tools (cross-app feature)
+    settings = get_settings()
+    if settings.vector_sync_enabled:
+        logger.info("Configuring semantic search tools (vector sync enabled)")
+        configure_semantic_tools(mcp)
+    else:
+        logger.info("Skipping semantic search tools (VECTOR_SYNC_ENABLED not set)")
+
     # Register OAuth provisioning tools (only when offline access is enabled)
     # With token exchange enabled (external IdP), provisioning is not needed for MCP operations
     enable_token_exchange = (
@@ -913,7 +1058,7 @@ def get_app(transport: str = "sse", enabled_apps: list[str] | None = None):
                 # browser_app is in the same function scope (defined later in create_app)
                 # We need to find it in the mounted routes
                 for route in app.routes:
-                    if isinstance(route, Mount) and route.path == "/user":
+                    if isinstance(route, Mount) and route.path == "/app":
                         route.app.state.oauth_context = oauth_context_dict
                         logger.info(
                             "OAuth context shared with browser_app for session auth"
@@ -923,10 +1068,126 @@ def get_app(transport: str = "sse", enabled_apps: list[str] | None = None):
                 logger.info(
                     f"OAuth context initialized for login routes (client_id={client_id[:16]}...)"
                 )
+            else:
+                # BasicAuth mode - share storage with browser_app for webhook management
+                from nextcloud_mcp_server.auth.storage import RefreshTokenStorage
 
-            async with AsyncExitStack() as stack:
-                await stack.enter_async_context(mcp.session_manager.run())
-                yield
+                storage = RefreshTokenStorage.from_env()
+                await storage.initialize()
+
+                app.state.storage = storage
+
+                # Also share with browser_app for webhook routes
+                for route in app.routes:
+                    if isinstance(route, Mount) and route.path == "/app":
+                        route.app.state.storage = storage
+                        logger.info(
+                            "Storage shared with browser_app for webhook management"
+                        )
+                        break
+
+            # Start background vector sync tasks for BasicAuth mode (ADR-007)
+            # For streamable-http transport, FastMCP lifespan isn't automatically triggered
+            # so we manually start background tasks here if vector sync is enabled
+            import anyio as anyio_module
+
+            settings = get_settings()
+            if not oauth_enabled and settings.vector_sync_enabled:
+                logger.info("Starting background vector sync tasks for BasicAuth mode")
+
+                # Get username from environment
+                username = os.getenv("NEXTCLOUD_USERNAME")
+                if not username:
+                    raise ValueError(
+                        "NEXTCLOUD_USERNAME required for vector sync in BasicAuth mode"
+                    )
+
+                # Get Nextcloud client from MCP app context
+                # Create client since we're outside FastMCP lifespan
+                client = NextcloudClient.from_env()
+
+                # Initialize Qdrant collection before starting background tasks
+                logger.info("Initializing Qdrant collection...")
+                from nextcloud_mcp_server.vector.qdrant_client import get_qdrant_client
+
+                try:
+                    await get_qdrant_client()  # Triggers collection creation if needed
+                    logger.info("Qdrant collection ready")
+                except Exception as e:
+                    logger.error(f"Failed to initialize Qdrant collection: {e}")
+                    raise RuntimeError(
+                        f"Cannot start vector sync - Qdrant initialization failed: {e}"
+                    ) from e
+
+                # Initialize shared state
+                send_stream, receive_stream = anyio_module.create_memory_object_stream(
+                    max_buffer_size=settings.vector_sync_queue_max_size
+                )
+                shutdown_event = anyio_module.Event()
+                scanner_wake_event = anyio_module.Event()
+
+                # Store in app state for access from routes (ADR-007)
+                app.state.document_send_stream = send_stream
+                app.state.document_receive_stream = receive_stream
+                app.state.shutdown_event = shutdown_event
+                app.state.scanner_wake_event = scanner_wake_event
+
+                # Also share with browser_app for /app route
+                for route in app.routes:
+                    if isinstance(route, Mount) and route.path == "/app":
+                        route.app.state.document_send_stream = send_stream
+                        route.app.state.document_receive_stream = receive_stream
+                        route.app.state.shutdown_event = shutdown_event
+                        route.app.state.scanner_wake_event = scanner_wake_event
+                        logger.info(
+                            "Vector sync state shared with browser_app for /app"
+                        )
+                        break
+
+                # Start background tasks using anyio TaskGroup
+                async with anyio_module.create_task_group() as tg:
+                    # Start scanner task
+                    await tg.start(
+                        scanner_task,
+                        send_stream,
+                        shutdown_event,
+                        scanner_wake_event,
+                        client,
+                        username,
+                    )
+
+                    # Start processor pool (each gets a cloned receive stream)
+                    for i in range(settings.vector_sync_processor_workers):
+                        await tg.start(
+                            processor_task,
+                            i,
+                            receive_stream.clone(),
+                            shutdown_event,
+                            client,
+                            username,
+                        )
+
+                    logger.info(
+                        f"Background sync tasks started: 1 scanner + "
+                        f"{settings.vector_sync_processor_workers} processors"
+                    )
+
+                    # Run MCP session manager and yield
+                    async with AsyncExitStack() as stack:
+                        await stack.enter_async_context(mcp.session_manager.run())
+                        try:
+                            yield
+                        finally:
+                            # Shutdown signal
+                            logger.info("Shutting down background sync tasks")
+                            shutdown_event.set()
+                            await client.close()
+                            # TaskGroup automatically cancels all tasks on exit
+            else:
+                # No vector sync - just run MCP session manager
+                async with AsyncExitStack() as stack:
+                    await stack.enter_async_context(mcp.session_manager.run())
+                    yield
 
     # Health check endpoints for Kubernetes probes
     def health_live(request):
@@ -946,17 +1207,40 @@ def get_app(transport: str = "sse", enabled_apps: list[str] | None = None):
         """Readiness probe endpoint.
 
         Returns 200 OK if the application is ready to serve traffic.
-        Checks that required configuration is present.
+        Checks that required configuration is present and Qdrant if vector sync enabled.
         """
         checks = {}
         is_ready = True
 
-        # Check Nextcloud host configuration
+        # Check Nextcloud host configuration and connectivity
         nextcloud_host = os.getenv("NEXTCLOUD_HOST")
         if nextcloud_host:
             checks["nextcloud_configured"] = "ok"
+            # Try to connect to Nextcloud
+            start_time = time.time()
+            try:
+                async with httpx.AsyncClient(timeout=2.0) as client:
+                    response = await client.get(f"{nextcloud_host}/status.php")
+                    duration = time.time() - start_time
+                    if response.status_code == 200:
+                        checks["nextcloud_reachable"] = "ok"
+                        set_dependency_health("nextcloud", True)
+                    else:
+                        checks["nextcloud_reachable"] = (
+                            f"error: status {response.status_code}"
+                        )
+                        set_dependency_health("nextcloud", False)
+                        is_ready = False
+                    record_dependency_check("nextcloud", duration)
+            except Exception as e:
+                duration = time.time() - start_time
+                checks["nextcloud_reachable"] = f"error: {str(e)}"
+                set_dependency_health("nextcloud", False)
+                record_dependency_check("nextcloud", duration)
+                is_ready = False
         else:
             checks["nextcloud_configured"] = "error: NEXTCLOUD_HOST not set"
+            set_dependency_health("nextcloud", False)
             is_ready = False
 
         # Check authentication configuration
@@ -976,6 +1260,38 @@ def get_app(transport: str = "sse", enabled_apps: list[str] | None = None):
                 checks["auth_configured"] = "error: credentials not set"
                 is_ready = False
 
+        # Check Qdrant status if using network mode (external Qdrant service)
+        # In-memory and persistent modes use embedded Qdrant, no external service to check
+        vector_sync_enabled = (
+            os.getenv("VECTOR_SYNC_ENABLED", "false").lower() == "true"
+        )
+        qdrant_url = os.getenv("QDRANT_URL")  # Only set in network mode
+
+        if vector_sync_enabled and qdrant_url:
+            start_time = time.time()
+            try:
+                async with httpx.AsyncClient(timeout=2.0) as client:
+                    response = await client.get(f"{qdrant_url}/readyz")
+                    duration = time.time() - start_time
+                    if response.status_code == 200:
+                        checks["qdrant"] = "ok"
+                        set_dependency_health("qdrant", True)
+                    else:
+                        checks["qdrant"] = f"error: status {response.status_code}"
+                        set_dependency_health("qdrant", False)
+                        is_ready = False
+                    record_dependency_check("qdrant", duration)
+            except Exception as e:
+                duration = time.time() - start_time
+                checks["qdrant"] = f"error: {str(e)}"
+                set_dependency_health("qdrant", False)
+                record_dependency_check("qdrant", duration)
+                is_ready = False
+        elif vector_sync_enabled:
+            # Using embedded Qdrant (memory or persistent mode)
+            checks["qdrant"] = "embedded"
+            set_dependency_health("qdrant", True)
+
         status_code = 200 if is_ready else 503
         return JSONResponse(
             {
@@ -985,6 +1301,31 @@ def get_app(transport: str = "sse", enabled_apps: list[str] | None = None):
             status_code=status_code,
         )
 
+    async def handle_nextcloud_webhook(request):
+        """Test webhook endpoint to capture and log Nextcloud webhook payloads.
+
+        This is a temporary endpoint for testing webhook schemas and payloads.
+        It logs the full payload and returns 200 OK immediately.
+        """
+        import json
+
+        try:
+            payload = await request.json()
+            logger.info("=" * 80)
+            logger.info("🔔 Webhook received from Nextcloud:")
+            logger.info(json.dumps(payload, indent=2, sort_keys=True))
+            logger.info("=" * 80)
+
+            return JSONResponse(
+                {"status": "received", "timestamp": payload.get("time")},
+                status_code=200,
+            )
+        except Exception as e:
+            logger.error(f"❌ Failed to parse webhook payload: {e}")
+            return JSONResponse(
+                {"error": "invalid_payload", "message": str(e)}, status_code=400
+            )
+
     # Add Protected Resource Metadata (PRM) endpoint for OAuth mode
     routes = []
 
@@ -993,6 +1334,15 @@ def get_app(transport: str = "sse", enabled_apps: list[str] | None = None):
     routes.append(Route("/health/ready", health_ready, methods=["GET"]))
     logger.info("Health check endpoints enabled: /health/live, /health/ready")
 
+    # Add test webhook endpoint (for development/testing)
+    routes.append(
+        Route("/webhooks/nextcloud", handle_nextcloud_webhook, methods=["POST"])
+    )
+    logger.info("Test webhook endpoint enabled: /webhooks/nextcloud")
+
+    # Note: Metrics endpoint is NOT exposed on main HTTP port for security reasons.
+    # Metrics are served on dedicated port via setup_metrics() (default: 9090)
+
     if oauth_enabled:
         # Import OAuth routes (ADR-004 Progressive Consent)
         from nextcloud_mcp_server.auth.oauth_routes import oauth_authorize
@@ -1125,17 +1475,50 @@ def get_app(transport: str = "sse", enabled_apps: list[str] | None = None):
     from nextcloud_mcp_server.auth.userinfo_routes import (
         revoke_session,
         user_info_html,
-        user_info_json,
+        vector_sync_status_fragment,
+    )
+    from nextcloud_mcp_server.auth.viz_routes import (
+        vector_visualization_html,
+        vector_visualization_search,
+    )
+    from nextcloud_mcp_server.auth.webhook_routes import (
+        disable_webhook_preset,
+        enable_webhook_preset,
+        webhook_management_pane,
     )
 
     # Create a separate Starlette app for browser routes that need session auth
     # This prevents SessionAuthBackend from interfering with FastMCP's OAuth
     browser_routes = [
-        Route("/", user_info_json, methods=["GET"]),  # /user/ → user_info_json
-        Route("/page", user_info_html, methods=["GET"]),  # /user/page → user_info_html
+        Route("/", user_info_html, methods=["GET"]),  # /app → webapp (HTML UI)
         Route(
             "/revoke", revoke_session, methods=["POST"], name="revoke_session_endpoint"
-        ),  # /user/revoke → revoke_session
+        ),  # /app/revoke → revoke_session
+        # Vector sync status fragment (htmx polling)
+        Route(
+            "/vector-sync/status",
+            vector_sync_status_fragment,
+            methods=["GET"],
+        ),  # /app/vector-sync/status
+        # Vector visualization routes
+        Route(
+            "/vector-viz", vector_visualization_html, methods=["GET"]
+        ),  # /app/vector-viz
+        Route(
+            "/vector-viz/search",
+            vector_visualization_search,
+            methods=["GET"],
+        ),  # /app/vector-viz/search
+        # Webhook management routes (admin-only)
+        Route("/webhooks", webhook_management_pane, methods=["GET"]),  # /app/webhooks
+        Route(
+            "/webhooks/enable/{preset_id:str}", enable_webhook_preset, methods=["POST"]
+        ),
+        Route(
+            "/webhooks/disable/{preset_id:str}",
+            disable_webhook_preset,
+            methods=["DELETE"],
+        ),
     ]
 
     browser_app = Starlette(routes=browser_routes)
@@ -1144,9 +1527,14 @@ def get_app(transport: str = "sse", enabled_apps: list[str] | None = None):
         backend=SessionAuthBackend(oauth_enabled=oauth_enabled),
     )
 
-    # Mount browser app at /user (so /user and /user/page work)
-    routes.append(Mount("/user", app=browser_app))
-    logger.info("User info routes with session auth: /user, /user/page")
+    # Add redirect from /app to /app/ (Starlette requires trailing slash for mounted apps)
+    routes.append(
+        Route("/app", lambda request: RedirectResponse("/app/", status_code=307))
+    )
+
+    # Mount browser app at /app (webapp and admin routes)
+    routes.append(Mount("/app", app=browser_app))
+    logger.info("App routes with session auth: /app, /app/webhooks, /app/revoke")
 
     # Mount FastMCP at root last (catch-all, handles OAuth via token_verifier)
     routes.append(Mount("/", app=mcp_app))
@@ -1156,7 +1544,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
+    # Add debugging middleware to log Authorization headers and client capabilities
     @app.middleware("http")
     async def log_auth_headers(request, call_next):
         auth_header = request.headers.get("authorization")
@@ -1168,9 +1556,58 @@ def get_app(transport: str = "sse", enabled_apps: list[str] | None = None):
                 )
                 logger.info(f"🔑 /mcp request with Authorization: {token_preview}")
             else:
-                logger.warning(
-                    f"⚠️  /mcp request WITHOUT Authorization header from {request.client}"
-                )
+                # Only warn about missing Authorization in OAuth mode
+                # In BasicAuth mode, /mcp requests without Authorization are expected
+                if oauth_enabled:
+                    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
 
@@ -1184,6 +1621,11 @@ def get_app(transport: str = "sse", enabled_apps: list[str] | None = None):
         expose_headers=["*"],
     )
 
+    # Add observability middleware (metrics + tracing)
+    if settings.metrics_enabled or settings.otel_exporter_otlp_endpoint:
+        app.add_middleware(ObservabilityMiddleware)
+        logger.info("Observability middleware enabled (metrics and/or tracing)")
+
     # Add exception handler for scope challenges (OAuth mode only)
     if oauth_enabled:
 
@@ -1213,237 +1655,3 @@ def get_app(transport: str = "sse", enabled_apps: list[str] | None = None):
         logger.info("WWW-Authenticate scope challenge handler enabled")
 
     return app
-
-
-@click.command()
-@click.option(
-    "--host", "-h", default="127.0.0.1", show_default=True, help="Server host"
-)
-@click.option(
-    "--port", "-p", type=int, default=8000, show_default=True, help="Server port"
-)
-@click.option(
-    "--log-level",
-    "-l",
-    default="info",
-    show_default=True,
-    type=click.Choice(["critical", "error", "warning", "info", "debug", "trace"]),
-    help="Logging level",
-)
-@click.option(
-    "--transport",
-    "-t",
-    default="sse",
-    show_default=True,
-    type=click.Choice(["sse", "streamable-http", "http"]),
-    help="MCP transport protocol",
-)
-@click.option(
-    "--enable-app",
-    "-e",
-    multiple=True,
-    type=click.Choice(
-        ["notes", "tables", "webdav", "calendar", "contacts", "cookbook", "deck"]
-    ),
-    help="Enable specific Nextcloud app APIs. Can be specified multiple times. If not specified, all apps are enabled.",
-)
-@click.option(
-    "--oauth/--no-oauth",
-    default=None,
-    help="Force OAuth mode (if enabled) or BasicAuth mode (if disabled). By default, auto-detected based on environment variables.",
-)
-@click.option(
-    "--oauth-client-id",
-    envvar="NEXTCLOUD_OIDC_CLIENT_ID",
-    help="OAuth client ID (can also use NEXTCLOUD_OIDC_CLIENT_ID env var)",
-)
-@click.option(
-    "--oauth-client-secret",
-    envvar="NEXTCLOUD_OIDC_CLIENT_SECRET",
-    help="OAuth client secret (can also use NEXTCLOUD_OIDC_CLIENT_SECRET env var)",
-)
-@click.option(
-    "--mcp-server-url",
-    envvar="NEXTCLOUD_MCP_SERVER_URL",
-    default="http://localhost:8000",
-    show_default=True,
-    help="MCP server URL for OAuth callbacks (can also use NEXTCLOUD_MCP_SERVER_URL env var)",
-)
-@click.option(
-    "--nextcloud-host",
-    envvar="NEXTCLOUD_HOST",
-    help="Nextcloud instance URL (can also use NEXTCLOUD_HOST env var)",
-)
-@click.option(
-    "--nextcloud-username",
-    envvar="NEXTCLOUD_USERNAME",
-    help="Nextcloud username for BasicAuth (can also use NEXTCLOUD_USERNAME env var)",
-)
-@click.option(
-    "--nextcloud-password",
-    envvar="NEXTCLOUD_PASSWORD",
-    help="Nextcloud password for BasicAuth (can also use NEXTCLOUD_PASSWORD env var)",
-)
-@click.option(
-    "--oauth-scopes",
-    envvar="NEXTCLOUD_OIDC_SCOPES",
-    default="openid profile email notes:read notes:write calendar:read calendar:write todo:read todo:write contacts:read contacts:write cookbook:read cookbook:write deck:read deck:write tables:read tables:write files:read files:write sharing:read sharing:write",
-    show_default=True,
-    help="OAuth scopes to request during client registration. These define the maximum allowed scopes for the client. Note: Actual supported scopes are discovered dynamically from MCP tools at runtime. (can also use NEXTCLOUD_OIDC_SCOPES env var)",
-)
-@click.option(
-    "--oauth-token-type",
-    envvar="NEXTCLOUD_OIDC_TOKEN_TYPE",
-    default="bearer",
-    show_default=True,
-    type=click.Choice(["bearer", "jwt"], case_sensitive=False),
-    help="OAuth token type (can also use NEXTCLOUD_OIDC_TOKEN_TYPE env var)",
-)
-@click.option(
-    "--public-issuer-url",
-    envvar="NEXTCLOUD_PUBLIC_ISSUER_URL",
-    help="Public issuer URL for OAuth (can also use NEXTCLOUD_PUBLIC_ISSUER_URL env var)",
-)
-def run(
-    host: str,
-    port: int,
-    log_level: str,
-    transport: str,
-    enable_app: tuple[str, ...],
-    oauth: bool | None,
-    oauth_client_id: str | None,
-    oauth_client_secret: str | None,
-    mcp_server_url: str,
-    nextcloud_host: str | None,
-    nextcloud_username: str | None,
-    nextcloud_password: str | None,
-    oauth_scopes: str,
-    oauth_token_type: str,
-    public_issuer_url: str | None,
-):
-    """
-    Run the Nextcloud MCP server.
-
-    \b
-    Authentication Modes:
-      - BasicAuth: Set NEXTCLOUD_USERNAME and NEXTCLOUD_PASSWORD
-      - OAuth: Leave USERNAME/PASSWORD unset (requires OIDC app enabled)
-
-    \b
-    Examples:
-      # BasicAuth mode with CLI options
-      $ nextcloud-mcp-server --nextcloud-host=https://cloud.example.com \\
-          --nextcloud-username=admin --nextcloud-password=secret
-
-      # BasicAuth mode with env vars (recommended for credentials)
-      $ export NEXTCLOUD_HOST=https://cloud.example.com
-      $ export NEXTCLOUD_USERNAME=admin
-      $ export NEXTCLOUD_PASSWORD=secret
-      $ nextcloud-mcp-server --host 0.0.0.0 --port 8000
-
-      # OAuth mode with auto-registration
-      $ nextcloud-mcp-server --nextcloud-host=https://cloud.example.com --oauth
-
-      # OAuth mode with pre-configured client
-      $ nextcloud-mcp-server --nextcloud-host=https://cloud.example.com --oauth \\
-          --oauth-client-id=xxx --oauth-client-secret=yyy
-
-      # OAuth mode with custom scopes and JWT tokens
-      $ nextcloud-mcp-server --nextcloud-host=https://cloud.example.com --oauth \\
-          --oauth-scopes="openid notes:read notes:write" --oauth-token-type=jwt
-
-      # OAuth with public issuer URL (for Docker/proxy setups)
-      $ nextcloud-mcp-server --nextcloud-host=http://app --oauth \\
-          --public-issuer-url=http://localhost:8080
-    """
-    # Set env vars from CLI options if provided
-    if nextcloud_host:
-        os.environ["NEXTCLOUD_HOST"] = nextcloud_host
-    if nextcloud_username:
-        os.environ["NEXTCLOUD_USERNAME"] = nextcloud_username
-    if nextcloud_password:
-        os.environ["NEXTCLOUD_PASSWORD"] = nextcloud_password
-    if oauth_client_id:
-        os.environ["NEXTCLOUD_OIDC_CLIENT_ID"] = oauth_client_id
-    if oauth_client_secret:
-        os.environ["NEXTCLOUD_OIDC_CLIENT_SECRET"] = oauth_client_secret
-    if oauth_scopes:
-        os.environ["NEXTCLOUD_OIDC_SCOPES"] = oauth_scopes
-    if oauth_token_type:
-        os.environ["NEXTCLOUD_OIDC_TOKEN_TYPE"] = oauth_token_type
-    if mcp_server_url:
-        os.environ["NEXTCLOUD_MCP_SERVER_URL"] = mcp_server_url
-    if public_issuer_url:
-        os.environ["NEXTCLOUD_PUBLIC_ISSUER_URL"] = public_issuer_url
-
-    # Force OAuth mode if explicitly requested
-    if oauth is True:
-        # Clear username/password to force OAuth mode
-        if "NEXTCLOUD_USERNAME" in os.environ:
-            click.echo(
-                "Warning: --oauth flag set, ignoring NEXTCLOUD_USERNAME", err=True
-            )
-            del os.environ["NEXTCLOUD_USERNAME"]
-        if "NEXTCLOUD_PASSWORD" in os.environ:
-            click.echo(
-                "Warning: --oauth flag set, ignoring NEXTCLOUD_PASSWORD", err=True
-            )
-            del os.environ["NEXTCLOUD_PASSWORD"]
-
-        # Validate OAuth configuration
-        nextcloud_host = os.getenv("NEXTCLOUD_HOST")
-        if not nextcloud_host:
-            raise click.ClickException(
-                "OAuth mode requires NEXTCLOUD_HOST environment variable to be set"
-            )
-
-        # Check if we have client credentials OR if dynamic registration is possible
-        has_client_creds = os.getenv("NEXTCLOUD_OIDC_CLIENT_ID") and os.getenv(
-            "NEXTCLOUD_OIDC_CLIENT_SECRET"
-        )
-
-        if not has_client_creds:
-            # No client credentials - will attempt dynamic registration
-            # Show helpful message before server starts
-            click.echo("", err=True)
-            click.echo("OAuth Configuration:", err=True)
-            click.echo("  Mode: Dynamic Client Registration", err=True)
-            click.echo("  Host: " + nextcloud_host, err=True)
-            click.echo("  Storage: SQLite (TOKEN_STORAGE_DB)", err=True)
-            click.echo("", err=True)
-            click.echo(
-                "Note: Make sure 'Dynamic Client Registration' is enabled", err=True
-            )
-            click.echo("      in your Nextcloud OIDC app settings.", err=True)
-            click.echo("", err=True)
-        else:
-            click.echo("", err=True)
-            click.echo("OAuth Configuration:", err=True)
-            click.echo("  Mode: Pre-configured Client", err=True)
-            click.echo("  Host: " + nextcloud_host, err=True)
-            click.echo(
-                "  Client ID: "
-                + os.getenv("NEXTCLOUD_OIDC_CLIENT_ID", "")[:16]
-                + "...",
-                err=True,
-            )
-            click.echo("", err=True)
-
-    elif oauth is False:
-        # Force BasicAuth mode - verify credentials exist
-        if not os.getenv("NEXTCLOUD_USERNAME") or not os.getenv("NEXTCLOUD_PASSWORD"):
-            raise click.ClickException(
-                "--no-oauth flag set but NEXTCLOUD_USERNAME or NEXTCLOUD_PASSWORD not set"
-            )
-
-    enabled_apps = list(enable_app) if enable_app else None
-
-    app = get_app(transport=transport, enabled_apps=enabled_apps)
-
-    uvicorn.run(
-        app=app, host=host, port=port, log_level=log_level, log_config=LOGGING_CONFIG
-    )
-
-
-if __name__ == "__main__":
-    run()

nextcloud_mcp_server/auth/browser_oauth_routes.py

@@ -1,7 +1,7 @@
 """Browser-based OAuth login routes for admin UI.
 
 Separate from MCP OAuth flow - these routes establish browser sessions
-for accessing admin UI endpoints like /user/page.
+for accessing admin UI endpoints like /app.
 """
 
 import hashlib
@@ -38,8 +38,8 @@ async def oauth_login(request: Request) -> RedirectResponse | JSONResponse:
     """
     oauth_ctx = request.app.state.oauth_context
     if not oauth_ctx:
-        # BasicAuth mode - no login needed, redirect to user page
-        return RedirectResponse("/user/page", status_code=302)
+        # BasicAuth mode - no login needed, redirect to app
+        return RedirectResponse("/app", status_code=302)
 
     storage = oauth_ctx["storage"]
     oauth_client = oauth_ctx["oauth_client"]
@@ -71,7 +71,7 @@ async def oauth_login(request: Request) -> RedirectResponse | JSONResponse:
     await storage.store_oauth_session(
         session_id=state,  # Use state as session ID
         client_id="browser-ui",
-        client_redirect_uri="/user/page",
+        client_redirect_uri="/app",
         state=state,
         code_challenge=code_challenge,
         code_challenge_method="S256",
@@ -383,7 +383,7 @@ async def oauth_login_callback(request: Request) -> RedirectResponse | HTMLRespo
             # Continue anyway - profile cache is optional for browser UI
 
     # Create response and set session cookie
-    response = RedirectResponse("/user/page", status_code=302)
+    response = RedirectResponse("/app", status_code=302)
     response.set_cookie(
         key="mcp_session",
         value=user_id,

nextcloud_mcp_server/auth/client_registration.py

@@ -8,7 +8,7 @@ from typing import Any
 import anyio
 import httpx
 
-from nextcloud_mcp_server.auth.refresh_token_storage import RefreshTokenStorage
+from nextcloud_mcp_server.auth.storage import RefreshTokenStorage
 
 logger = logging.getLogger(__name__)
 
@@ -79,19 +79,22 @@ async def register_client(
     client_name: str = "Nextcloud MCP Server",
     redirect_uris: list[str] | None = None,
     scopes: str = "openid profile email",
-    token_type: str = "Bearer",
+    token_type: str | None = "Bearer",
     resource_url: str | None = None,
 ) -> ClientInfo:
     """
-    Register a new OAuth client with Nextcloud OIDC using dynamic client registration.
+    Register a new OAuth client using RFC 7591 Dynamic Client Registration.
+
+    This function supports both Nextcloud OIDC and standard OIDC providers like Keycloak.
 
     Args:
-        nextcloud_url: Base URL of the Nextcloud instance
+        nextcloud_url: Base URL of the OIDC provider
         registration_endpoint: Full URL to the registration endpoint
         client_name: Name of the client application
         redirect_uris: List of redirect URIs (default: http://localhost:8000/oauth/callback)
         scopes: Space-separated list of scopes to request
-        token_type: Type of access tokens to issue (default: "Bearer", also supports "JWT")
+        token_type: Type of access tokens (default: "Bearer", supports "JWT" for Nextcloud).
+                    Set to None to omit this field (required for Keycloak and other standard providers).
         resource_url: OAuth 2.0 Protected Resource URL (RFC 9728) - used for token introspection authorization
 
     Returns:
@@ -100,6 +103,11 @@ async def register_client(
     Raises:
         httpx.HTTPStatusError: If registration fails
         ValueError: If response is invalid
+
+    Note:
+        The token_type parameter is a Nextcloud-specific extension and is not part of RFC 7591.
+        Standard OIDC providers like Keycloak do not accept this field and will return a 400 error
+        if it's included. Set token_type=None when registering with Keycloak or other standard providers.
     """
     if redirect_uris is None:
         redirect_uris = ["http://localhost:8000/oauth/callback"]
@@ -111,9 +119,12 @@ async def register_client(
         "grant_types": ["authorization_code", "refresh_token"],
         "response_types": ["code"],
         "scope": scopes,
-        "token_type": token_type,
     }
 
+    # Add token_type if provided (Nextcloud-specific, not RFC 7591 standard)
+    if token_type is not None:
+        client_metadata["token_type"] = token_type
+
     # Add resource_url if provided (RFC 9728)
     if resource_url:
         client_metadata["resource_url"] = resource_url

nextcloud_mcp_server/auth/context_helper.py

@@ -12,6 +12,10 @@ from mcp.server.fastmcp import Context
 
 from ..client import NextcloudClient
 from ..config import get_settings
+from ..observability.metrics import (
+    oauth_token_cache_hits_total,
+    oauth_token_exchange_total,
+)
 from .token_exchange import exchange_token_for_audience
 
 logger = logging.getLogger(__name__)
@@ -138,6 +142,7 @@ async def get_session_client_from_context(
                 logger.debug(
                     f"Using cached exchanged token (expires in {expiry - time.time():.1f}s)"
                 )
+                oauth_token_cache_hits_total.labels(hit="true").inc()
                 return NextcloudClient.from_token(
                     base_url=base_url, token=cached_token, username=username
                 )
@@ -145,17 +150,24 @@ async def get_session_client_from_context(
                 logger.debug("Cached token expired, removing from cache")
                 del _exchange_cache[cache_key]
 
+        oauth_token_cache_hits_total.labels(hit="false").inc()
+
         # Perform RFC 8693 token exchange
         logger.info(f"Exchanging MCP token for Nextcloud API token (user: {username})")
 
-        # Exchange for Nextcloud resource URI audience
-        exchanged_token, expires_in = await exchange_token_for_audience(
-            subject_token=mcp_token,
-            requested_audience=settings.nextcloud_resource_uri or "nextcloud",
-            requested_scopes=None,  # Nextcloud doesn't support scopes
-        )
+        try:
+            # Exchange for Nextcloud resource URI audience
+            exchanged_token, expires_in = await exchange_token_for_audience(
+                subject_token=mcp_token,
+                requested_audience=settings.nextcloud_resource_uri or "nextcloud",
+                requested_scopes=None,  # Nextcloud doesn't support scopes
+            )
+            oauth_token_exchange_total.labels(status="success").inc()
 
-        logger.info(f"Token exchange successful. Token expires in {expires_in}s")
+            logger.info(f"Token exchange successful. Token expires in {expires_in}s")
+        except Exception:
+            oauth_token_exchange_total.labels(status="error").inc()
+            raise
 
         # Cache the exchanged token
         # Use the minimum of exchange TTL and configured cache TTL

nextcloud_mcp_server/auth/oauth_routes.py

@@ -32,7 +32,7 @@ from starlette.requests import Request
 from starlette.responses import JSONResponse, RedirectResponse
 
 from nextcloud_mcp_server.auth.client_registry import get_client_registry
-from nextcloud_mcp_server.auth.refresh_token_storage import RefreshTokenStorage
+from nextcloud_mcp_server.auth.storage import RefreshTokenStorage
 
 logger = logging.getLogger(__name__)
 

nextcloud_mcp_server/auth/permissions.py

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

nextcloud_mcp_server/auth/provisioning_decorator.py

@@ -13,7 +13,7 @@ from mcp.server.fastmcp import Context
 from mcp.shared.exceptions import McpError
 from mcp.types import ErrorData
 
-from nextcloud_mcp_server.auth.refresh_token_storage import RefreshTokenStorage
+from nextcloud_mcp_server.auth.storage import RefreshTokenStorage
 
 logger = logging.getLogger(__name__)
 

nextcloud_mcp_server/auth/storage.py

@@ -1,23 +1,28 @@
 """
-Refresh Token Storage for ADR-002 Tier 1: Offline Access
+Persistent Storage for MCP Server State
 
-Manages two separate concerns for OAuth authentication:
+This module provides SQLite-based storage for multiple concerns across both
+BasicAuth and OAuth authentication modes:
 
-1. **Refresh Tokens** (for background jobs ONLY)
+1. **Refresh Tokens** (OAuth mode only, for background jobs)
    - Securely stores encrypted refresh tokens for offline access
    - Used ONLY by background jobs to obtain access tokens
    - NEVER used within MCP client sessions or browser sessions
 
-2. **User Profile Cache** (for browser UI display ONLY)
+2. **User Profile Cache** (OAuth mode only, for browser UI display)
    - Caches IdP user profile data for browser-based admin UI
    - Queried ONCE at login, displayed from cache thereafter
    - NOT used for authorization decisions or background jobs
 
-IMPORTANT: These are separate concerns. Browser sessions read profile cache for
-display purposes. Background jobs use refresh tokens for API access. Never mix
-the two.
+3. **Webhook Registration Tracking** (both modes, for webhook management)
+   - Tracks registered webhook IDs mapped to presets
+   - Enables persistent webhook state across restarts
+   - Avoids redundant Nextcloud API calls for webhook status
 
-Tokens are encrypted at rest using Fernet symmetric encryption.
+IMPORTANT: The database is initialized in both BasicAuth and OAuth modes.
+Token storage requires TOKEN_ENCRYPTION_KEY, but webhook tracking does not.
+
+Sensitive data (tokens, secrets) is encrypted at rest using Fernet symmetric encryption.
 """
 
 import json
@@ -30,29 +35,40 @@ from typing import Any, Optional
 import aiosqlite
 from cryptography.fernet import Fernet
 
+from nextcloud_mcp_server.observability.metrics import record_db_operation
+
 logger = logging.getLogger(__name__)
 
 
 class RefreshTokenStorage:
-    """Securely store and manage user refresh tokens and profile cache.
+    """Persistent storage for MCP server state (tokens, webhooks, and future features).
 
-    This class manages two separate concerns:
-    - Refresh tokens: Encrypted storage for background job access (write-only by OAuth, read-only by background jobs)
-    - User profiles: Plain JSON cache for browser UI display (written at login, read by UI)
+    This class manages multiple concerns across both BasicAuth and OAuth modes:
 
-    These concerns are architecturally separate and should never be mixed.
+    **OAuth-specific concerns**:
+    - Refresh tokens: Encrypted storage for background job access (requires encryption key)
+    - User profiles: Plain JSON cache for browser UI display
+    - OAuth client credentials: Encrypted client secrets from DCR
+    - OAuth sessions: Temporary session state for progressive consent flow
+
+    **Both modes**:
+    - Webhook registration: Track registered webhooks mapped to presets
+    - Schema versioning: Handle database migrations automatically
+
+    Token-related operations require TOKEN_ENCRYPTION_KEY, but webhook operations do not.
     """
 
-    def __init__(self, db_path: str, encryption_key: bytes):
+    def __init__(self, db_path: str, encryption_key: bytes | None = None):
         """
-        Initialize refresh token storage.
+        Initialize persistent storage.
 
         Args:
             db_path: Path to SQLite database file
-            encryption_key: Fernet encryption key (32 bytes, base64-encoded)
+            encryption_key: Optional Fernet encryption key (32 bytes, base64-encoded).
+                          Required for token storage operations, not required for webhook tracking.
         """
         self.db_path = db_path
-        self.cipher = Fernet(encryption_key)
+        self.cipher = Fernet(encryption_key) if encryption_key else None
         self._initialized = False
 
     @classmethod
@@ -62,41 +78,42 @@ class RefreshTokenStorage:
 
         Environment variables:
             TOKEN_STORAGE_DB: Path to database file (default: /app/data/tokens.db)
-            TOKEN_ENCRYPTION_KEY: Base64-encoded Fernet key
+            TOKEN_ENCRYPTION_KEY: Optional base64-encoded Fernet key (required for token storage)
 
         Returns:
             RefreshTokenStorage instance
 
-        Raises:
-            ValueError: If TOKEN_ENCRYPTION_KEY is not set
+        Note:
+            If TOKEN_ENCRYPTION_KEY is not set, token storage operations will fail,
+            but webhook tracking will still work.
         """
         db_path = os.getenv("TOKEN_STORAGE_DB", "/app/data/tokens.db")
         encryption_key_b64 = os.getenv("TOKEN_ENCRYPTION_KEY")
 
-        if not encryption_key_b64:
-            raise ValueError(
-                "TOKEN_ENCRYPTION_KEY environment variable is required. "
-                "Generate one with: python -c 'from cryptography.fernet import Fernet; "
-                "print(Fernet.generate_key().decode())'"
+        encryption_key = None
+        if encryption_key_b64:
+            # Fernet expects a base64url-encoded key as bytes, not decoded bytes
+            # The key from Fernet.generate_key() is already base64url-encoded
+            try:
+                # Convert string to bytes if needed
+                if isinstance(encryption_key_b64, str):
+                    encryption_key = encryption_key_b64.encode()
+                else:
+                    encryption_key = encryption_key_b64
+
+                # Validate the key by trying to create a Fernet instance
+                Fernet(encryption_key)
+            except Exception as e:
+                raise ValueError(
+                    f"Invalid TOKEN_ENCRYPTION_KEY: {e}. "
+                    "Must be a valid Fernet key (base64url-encoded 32 bytes)."
+                ) from e
+        else:
+            logger.info(
+                "TOKEN_ENCRYPTION_KEY not set - token storage operations will be unavailable, "
+                "but webhook tracking will still work"
             )
 
-        # Fernet expects a base64url-encoded key as bytes, not decoded bytes
-        # The key from Fernet.generate_key() is already base64url-encoded
-        try:
-            # Convert string to bytes if needed
-            if isinstance(encryption_key_b64, str):
-                encryption_key = encryption_key_b64.encode()
-            else:
-                encryption_key = encryption_key_b64
-
-            # Validate the key by trying to create a Fernet instance
-            Fernet(encryption_key)
-        except Exception as e:
-            raise ValueError(
-                f"Invalid TOKEN_ENCRYPTION_KEY: {e}. "
-                "Must be a valid Fernet key (base64url-encoded 32 bytes)."
-            ) from e
-
         return cls(db_path=db_path, encryption_key=encryption_key)
 
     async def initialize(self) -> None:
@@ -204,6 +221,38 @@ class RefreshTokenStorage:
                 "ON oauth_sessions(mcp_authorization_code)"
             )
 
+            # Schema version tracking
+            await db.execute(
+                """
+                CREATE TABLE IF NOT EXISTS schema_version (
+                    version INTEGER PRIMARY KEY,
+                    applied_at REAL NOT NULL
+                )
+                """
+            )
+
+            # Registered webhooks tracking (both BasicAuth and OAuth modes)
+            await db.execute(
+                """
+                CREATE TABLE IF NOT EXISTS registered_webhooks (
+                    id INTEGER PRIMARY KEY AUTOINCREMENT,
+                    webhook_id INTEGER NOT NULL UNIQUE,
+                    preset_id TEXT NOT NULL,
+                    created_at REAL NOT NULL
+                )
+                """
+            )
+
+            # Create indexes for efficient webhook queries
+            await db.execute(
+                "CREATE INDEX IF NOT EXISTS idx_webhooks_preset "
+                "ON registered_webhooks(preset_id)"
+            )
+            await db.execute(
+                "CREATE INDEX IF NOT EXISTS idx_webhooks_created "
+                "ON registered_webhooks(created_at)"
+            )
+
             await db.commit()
 
         # Set restrictive permissions after creation
@@ -245,35 +294,43 @@ class RefreshTokenStorage:
         # For Flow 2, set provisioned_at timestamp
         provisioned_at = now if flow_type == "flow2" else None
 
-        async with aiosqlite.connect(self.db_path) as db:
-            await db.execute(
-                """
-                INSERT OR REPLACE INTO refresh_tokens
-                (user_id, encrypted_token, expires_at, created_at, updated_at,
-                 flow_type, token_audience, provisioned_at, provisioning_client_id, scopes)
-                VALUES (?, ?, ?, COALESCE((SELECT created_at FROM refresh_tokens WHERE user_id = ?), ?), ?,
-                        ?, ?, ?, ?, ?)
-                """,
-                (
-                    user_id,
-                    encrypted_token,
-                    expires_at,
-                    user_id,
-                    now,
-                    now,
-                    flow_type,
-                    token_audience,
-                    provisioned_at,
-                    provisioning_client_id,
-                    scopes_json,
-                ),
-            )
-            await db.commit()
+        start_time = time.time()
+        try:
+            async with aiosqlite.connect(self.db_path) as db:
+                await db.execute(
+                    """
+                    INSERT OR REPLACE INTO refresh_tokens
+                    (user_id, encrypted_token, expires_at, created_at, updated_at,
+                     flow_type, token_audience, provisioned_at, provisioning_client_id, scopes)
+                    VALUES (?, ?, ?, COALESCE((SELECT created_at FROM refresh_tokens WHERE user_id = ?), ?), ?,
+                            ?, ?, ?, ?, ?)
+                    """,
+                    (
+                        user_id,
+                        encrypted_token,
+                        expires_at,
+                        user_id,
+                        now,
+                        now,
+                        flow_type,
+                        token_audience,
+                        provisioned_at,
+                        provisioning_client_id,
+                        scopes_json,
+                    ),
+                )
+                await db.commit()
+            duration = time.time() - start_time
+            record_db_operation("sqlite", "insert", duration, "success")
 
-        logger.info(
-            f"Stored refresh token for user {user_id}"
-            + (f" (expires at {expires_at})" if expires_at else "")
-        )
+            logger.info(
+                f"Stored refresh token for user {user_id}"
+                + (f" (expires at {expires_at})" if expires_at else "")
+            )
+        except Exception:
+            duration = time.time() - start_time
+            record_db_operation("sqlite", "insert", duration, "error")
+            raise
 
         # Audit log
         await self._audit_log(
@@ -375,40 +432,45 @@ class RefreshTokenStorage:
         if not self._initialized:
             await self.initialize()
 
-        async with aiosqlite.connect(self.db_path) as db:
-            async with db.execute(
-                """
-                SELECT encrypted_token, expires_at, flow_type, token_audience,
-                       provisioned_at, provisioning_client_id, scopes
-                FROM refresh_tokens WHERE user_id = ?
-                """,
-                (user_id,),
-            ) as cursor:
-                row = await cursor.fetchone()
-
-        if not row:
-            logger.debug(f"No refresh token found for user {user_id}")
-            return None
-
-        (
-            encrypted_token,
-            expires_at,
-            flow_type,
-            token_audience,
-            provisioned_at,
-            provisioning_client_id,
-            scopes_json,
-        ) = row
-
-        # Check expiration
-        if expires_at is not None and expires_at < time.time():
-            logger.warning(
-                f"Refresh token for user {user_id} has expired (expired at {expires_at})"
-            )
-            await self.delete_refresh_token(user_id)
-            return None
-
+        start_time = time.time()
         try:
+            async with aiosqlite.connect(self.db_path) as db:
+                async with db.execute(
+                    """
+                    SELECT encrypted_token, expires_at, flow_type, token_audience,
+                           provisioned_at, provisioning_client_id, scopes
+                    FROM refresh_tokens WHERE user_id = ?
+                    """,
+                    (user_id,),
+                ) as cursor:
+                    row = await cursor.fetchone()
+
+            if not row:
+                logger.debug(f"No refresh token found for user {user_id}")
+                duration = time.time() - start_time
+                record_db_operation("sqlite", "select", duration, "success")
+                return None
+
+            (
+                encrypted_token,
+                expires_at,
+                flow_type,
+                token_audience,
+                provisioned_at,
+                provisioning_client_id,
+                scopes_json,
+            ) = row
+
+            # Check expiration
+            if expires_at is not None and expires_at < time.time():
+                logger.warning(
+                    f"Refresh token for user {user_id} has expired (expired at {expires_at})"
+                )
+                await self.delete_refresh_token(user_id)
+                duration = time.time() - start_time
+                record_db_operation("sqlite", "select", duration, "success")
+                return None
+
             decrypted_token = self.cipher.decrypt(encrypted_token).decode()
             scopes = json.loads(scopes_json) if scopes_json else None
 
@@ -416,6 +478,9 @@ class RefreshTokenStorage:
                 f"Retrieved refresh token for user {user_id} (flow_type: {flow_type})"
             )
 
+            duration = time.time() - start_time
+            record_db_operation("sqlite", "select", duration, "success")
+
             return {
                 "refresh_token": decrypted_token,
                 "expires_at": expires_at,
@@ -427,6 +492,8 @@ class RefreshTokenStorage:
                 "scopes": scopes,
             }
         except Exception as e:
+            duration = time.time() - start_time
+            record_db_operation("sqlite", "select", duration, "error")
             logger.error(f"Failed to decrypt refresh token for user {user_id}: {e}")
             return None
 
@@ -521,25 +588,34 @@ class RefreshTokenStorage:
         if not self._initialized:
             await self.initialize()
 
-        async with aiosqlite.connect(self.db_path) as db:
-            cursor = await db.execute(
-                "DELETE FROM refresh_tokens WHERE user_id = ?",
-                (user_id,),
-            )
-            await db.commit()
-            deleted = cursor.rowcount > 0
+        start_time = time.time()
+        try:
+            async with aiosqlite.connect(self.db_path) as db:
+                cursor = await db.execute(
+                    "DELETE FROM refresh_tokens WHERE user_id = ?",
+                    (user_id,),
+                )
+                await db.commit()
+                deleted = cursor.rowcount > 0
 
-        if deleted:
-            logger.info(f"Deleted refresh token for user {user_id}")
-            await self._audit_log(
-                event="delete_refresh_token",
-                user_id=user_id,
-                auth_method="offline_access",
-            )
-        else:
-            logger.debug(f"No refresh token to delete for user {user_id}")
+            duration = time.time() - start_time
+            record_db_operation("sqlite", "delete", duration, "success")
 
-        return deleted
+            if deleted:
+                logger.info(f"Deleted refresh token for user {user_id}")
+                await self._audit_log(
+                    event="delete_refresh_token",
+                    user_id=user_id,
+                    auth_method="offline_access",
+                )
+            else:
+                logger.debug(f"No refresh token to delete for user {user_id}")
+
+            return deleted
+        except Exception:
+            duration = time.time() - start_time
+            record_db_operation("sqlite", "delete", duration, "error")
+            raise
 
     async def get_all_user_ids(self) -> list[str]:
         """
@@ -1104,6 +1180,123 @@ class RefreshTokenStorage:
 
         return deleted
 
+    # ============================================================================
+    # Webhook Registration Tracking (both BasicAuth and OAuth modes)
+    # ============================================================================
+
+    async def store_webhook(self, webhook_id: int, preset_id: str) -> None:
+        """
+        Store registered webhook ID for tracking.
+
+        Args:
+            webhook_id: Nextcloud webhook ID
+            preset_id: Preset identifier (e.g., "notes_sync", "calendar_sync")
+        """
+        if not self._initialized:
+            await self.initialize()
+
+        async with aiosqlite.connect(self.db_path) as db:
+            await db.execute(
+                "INSERT OR REPLACE INTO registered_webhooks (webhook_id, preset_id, created_at) VALUES (?, ?, ?)",
+                (webhook_id, preset_id, time.time()),
+            )
+            await db.commit()
+
+        logger.debug(f"Stored webhook {webhook_id} for preset '{preset_id}'")
+
+    async def get_webhooks_by_preset(self, preset_id: str) -> list[int]:
+        """
+        Get all webhook IDs registered for a preset.
+
+        Args:
+            preset_id: Preset identifier
+
+        Returns:
+            List of webhook IDs
+        """
+        if not self._initialized:
+            await self.initialize()
+
+        async with aiosqlite.connect(self.db_path) as db:
+            cursor = await db.execute(
+                "SELECT webhook_id FROM registered_webhooks WHERE preset_id = ?",
+                (preset_id,),
+            )
+            rows = await cursor.fetchall()
+
+        return [row[0] for row in rows]
+
+    async def delete_webhook(self, webhook_id: int) -> bool:
+        """
+        Remove webhook from tracking.
+
+        Args:
+            webhook_id: Nextcloud webhook ID to remove
+
+        Returns:
+            True if webhook was deleted, False if not found
+        """
+        if not self._initialized:
+            await self.initialize()
+
+        async with aiosqlite.connect(self.db_path) as db:
+            cursor = await db.execute(
+                "DELETE FROM registered_webhooks WHERE webhook_id = ?", (webhook_id,)
+            )
+            await db.commit()
+            deleted = cursor.rowcount > 0
+
+        if deleted:
+            logger.debug(f"Deleted webhook {webhook_id} from tracking")
+
+        return deleted
+
+    async def list_all_webhooks(self) -> list[dict]:
+        """
+        List all tracked webhooks with metadata.
+
+        Returns:
+            List of webhook dictionaries with keys: webhook_id, preset_id, created_at
+        """
+        if not self._initialized:
+            await self.initialize()
+
+        async with aiosqlite.connect(self.db_path) as db:
+            cursor = await db.execute(
+                "SELECT webhook_id, preset_id, created_at FROM registered_webhooks ORDER BY created_at DESC"
+            )
+            rows = await cursor.fetchall()
+
+        return [
+            {"webhook_id": row[0], "preset_id": row[1], "created_at": row[2]}
+            for row in rows
+        ]
+
+    async def clear_preset_webhooks(self, preset_id: str) -> int:
+        """
+        Delete all webhooks for a preset (bulk operation).
+
+        Args:
+            preset_id: Preset identifier
+
+        Returns:
+            Number of webhooks deleted
+        """
+        if not self._initialized:
+            await self.initialize()
+
+        async with aiosqlite.connect(self.db_path) as db:
+            cursor = await db.execute(
+                "DELETE FROM registered_webhooks WHERE preset_id = ?", (preset_id,)
+            )
+            await db.commit()
+            deleted = cursor.rowcount
+
+        if deleted > 0:
+            logger.debug(f"Cleared {deleted} webhook(s) for preset '{preset_id}'")
+
+        return deleted
+
 
 async def generate_encryption_key() -> str:
     """
@@ -1117,7 +1310,7 @@ async def generate_encryption_key() -> str:
 
 # Example usage
 if __name__ == "__main__":
-    import asyncio
+    import anyio
 
     async def main():
         # Generate a key for testing
@@ -1125,4 +1318,4 @@ if __name__ == "__main__":
         print(f"Generated encryption key: {key}")
         print(f"Set this in your environment: export TOKEN_ENCRYPTION_KEY='{key}'")
 
-    asyncio.run(main())
+    anyio.run(main)

nextcloud_mcp_server/auth/token_broker.py

@@ -14,16 +14,16 @@ The Token Broker provides:
 - Session vs background token separation (RFC 8693)
 """
 
-import asyncio
 import logging
 from datetime import datetime, timedelta, timezone
 from typing import Dict, Optional, Tuple
 
+import anyio
 import httpx
 import jwt
 from cryptography.fernet import Fernet
 
-from nextcloud_mcp_server.auth.refresh_token_storage import RefreshTokenStorage
+from nextcloud_mcp_server.auth.storage import RefreshTokenStorage
 from nextcloud_mcp_server.auth.token_exchange import exchange_token_for_delegation
 
 logger = logging.getLogger(__name__)
@@ -43,7 +43,7 @@ class TokenCache:
         self._cache: Dict[str, Tuple[str, datetime]] = {}
         self._ttl = timedelta(seconds=ttl_seconds)
         self._early_refresh = timedelta(seconds=early_refresh_seconds)
-        self._lock = asyncio.Lock()
+        self._lock = anyio.Lock()
 
     async def get(self, user_id: str) -> Optional[str]:
         """Get cached token if valid."""

nextcloud_mcp_server/auth/token_exchange.py

@@ -20,7 +20,7 @@ import httpx
 import jwt
 
 from ..config import get_settings
-from .refresh_token_storage import RefreshTokenStorage
+from .storage import RefreshTokenStorage
 
 logger = logging.getLogger(__name__)
 

nextcloud_mcp_server/auth/unified_verifier.py

@@ -26,6 +26,10 @@ from jwt import PyJWKClient
 from mcp.server.auth.provider import AccessToken, TokenVerifier
 
 from nextcloud_mcp_server.config import Settings
+from nextcloud_mcp_server.observability.metrics import (
+    oauth_token_cache_hits_total,
+    record_oauth_token_validation,
+)
 
 logger = logging.getLogger(__name__)
 
@@ -105,8 +109,11 @@ class UnifiedTokenVerifier(TokenVerifier):
         cached = self._get_cached_token(token)
         if cached:
             logger.debug("Token found in cache")
+            oauth_token_cache_hits_total.labels(hit="true").inc()
             return cached
 
+        oauth_token_cache_hits_total.labels(hit="false").inc()
+
         # Both modes do the same validation (MCP audience only)
         return await self._verify_mcp_audience(token)
 
@@ -124,13 +131,24 @@ class UnifiedTokenVerifier(TokenVerifier):
         Returns:
             AccessToken if valid with MCP audience, None otherwise
         """
+        validation_method = "unknown"
         try:
             # Attempt JWT verification first
             if self._is_jwt_format(token) and self.jwks_client:
+                validation_method = "jwt"
                 payload = await self._verify_jwt_signature(token)
+                if payload:
+                    record_oauth_token_validation("jwt", "valid")
+                else:
+                    record_oauth_token_validation("jwt", "invalid")
             else:
                 # Fall back to introspection for opaque tokens
+                validation_method = "introspect"
                 payload = await self._introspect_token(token)
+                if payload:
+                    record_oauth_token_validation("introspect", "valid")
+                else:
+                    record_oauth_token_validation("introspect", "invalid")
                 if not payload:
                     return None
 
@@ -146,6 +164,8 @@ class UnifiedTokenVerifier(TokenVerifier):
                     f"Got {audiences}, need MCP ({self.settings.oidc_client_id} or "
                     f"{self.settings.nextcloud_mcp_server_url})"
                 )
+                # Record as invalid due to audience mismatch
+                record_oauth_token_validation(validation_method, "invalid")
                 return None
 
             # Log based on mode for clarity
@@ -163,6 +183,7 @@ class UnifiedTokenVerifier(TokenVerifier):
 
         except Exception as e:
             logger.error(f"Token verification failed: {e}")
+            record_oauth_token_validation(validation_method, "error")
             return None
 
     def _has_mcp_audience(self, payload: dict[str, Any]) -> bool:
@@ -231,17 +252,21 @@ class UnifiedTokenVerifier(TokenVerifier):
                 token,
                 signing_key.key,
                 algorithms=["RS256"],
-                issuer=self.settings.oidc_issuer
-                if hasattr(self.settings, "oidc_issuer")
-                else None,
+                issuer=(
+                    self.settings.oidc_issuer
+                    if hasattr(self.settings, "oidc_issuer")
+                    else None
+                ),
                 options={
                     "verify_signature": True,
                     "verify_exp": True,
                     "verify_iat": True,
-                    "verify_iss": True
-                    if hasattr(self.settings, "oidc_issuer")
-                    and self.settings.oidc_issuer
-                    else False,
+                    "verify_iss": (
+                        True
+                        if hasattr(self.settings, "oidc_issuer")
+                        and self.settings.oidc_issuer
+                        else False
+                    ),
                     "verify_aud": False,  # We handle audience validation separately
                 },
             )

nextcloud_mcp_server/auth/userinfo_routes.py

@@ -19,6 +19,191 @@ from starlette.responses import HTMLResponse, JSONResponse
 logger = logging.getLogger(__name__)
 
 
+async def _get_authenticated_client_for_userinfo(request: Request) -> httpx.AsyncClient:
+    """Get an authenticated HTTP client for user info page operations.
+
+    Args:
+        request: Starlette request object
+
+    Returns:
+        Authenticated httpx.AsyncClient
+    """
+    oauth_ctx = getattr(request.app.state, "oauth_context", None)
+
+    # BasicAuth mode - use credentials from environment
+    if not oauth_ctx:
+        nextcloud_host = os.getenv("NEXTCLOUD_HOST")
+        username = os.getenv("NEXTCLOUD_USERNAME")
+        password = os.getenv("NEXTCLOUD_PASSWORD")
+
+        if not all([nextcloud_host, username, password]):
+            raise RuntimeError("BasicAuth credentials not configured")
+
+        assert nextcloud_host is not None  # Type narrowing for type checker
+        return httpx.AsyncClient(
+            base_url=nextcloud_host,
+            auth=(username, password),
+            timeout=30.0,
+        )
+
+    # OAuth mode - get token from session
+    storage = oauth_ctx.get("storage")
+    session_id = request.cookies.get("mcp_session")
+
+    if not storage or not session_id:
+        raise RuntimeError("Session not found")
+
+    token_data = await storage.get_refresh_token(session_id)
+    if not token_data or "access_token" not in token_data:
+        raise RuntimeError("No access token found in session")
+
+    access_token = token_data["access_token"]
+    nextcloud_host = oauth_ctx.get("config", {}).get("nextcloud_host", "")
+
+    if not nextcloud_host:
+        raise RuntimeError("Nextcloud host not configured")
+
+    return httpx.AsyncClient(
+        base_url=nextcloud_host,
+        headers={"Authorization": f"Bearer {access_token}"},
+        timeout=30.0,
+    )
+
+
+async def _get_processing_status(request: Request) -> dict[str, Any] | None:
+    """Get vector sync processing status.
+
+    Returns processing status information including indexed count, pending count,
+    and sync status. Only available when VECTOR_SYNC_ENABLED=true.
+
+    Args:
+        request: Starlette request object
+
+    Returns:
+        Dictionary with processing status, or None if vector sync is disabled
+        or components are unavailable:
+        {
+            "indexed_count": int,  # Number of documents in Qdrant
+            "pending_count": int,  # Number of documents in queue
+            "status": str,  # "syncing" or "idle"
+        }
+    """
+    # Check if vector sync is enabled
+    vector_sync_enabled = os.getenv("VECTOR_SYNC_ENABLED", "false").lower() == "true"
+    if not vector_sync_enabled:
+        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")
+            return None
+
+        # Get pending count from stream statistics
+        stats = document_receive_stream.statistics()
+        pending_count = stats.current_buffer_used
+
+        # Get Qdrant client and query indexed count
+        indexed_count = 0
+        try:
+            from nextcloud_mcp_server.config import get_settings
+            from nextcloud_mcp_server.vector.qdrant_client import get_qdrant_client
+
+            settings = get_settings()
+            qdrant_client = await get_qdrant_client()
+
+            # Count documents in collection
+            count_result = await qdrant_client.count(
+                collection_name=settings.get_collection_name()
+            )
+            indexed_count = count_result.count
+
+        except Exception as e:
+            logger.warning(f"Failed to query Qdrant for indexed count: {e}")
+            # Continue with indexed_count = 0
+
+        # Determine status
+        status = "syncing" if pending_count > 0 else "idle"
+
+        return {
+            "indexed_count": indexed_count,
+            "pending_count": pending_count,
+            "status": status,
+        }
+
+    except Exception as e:
+        logger.error(f"Error getting processing status: {e}")
+        return None
+
+
+@requires("authenticated", redirect="oauth_login")
+async def vector_sync_status_fragment(request: Request) -> HTMLResponse:
+    """Vector sync status fragment endpoint - returns HTML fragment with current status.
+
+    This endpoint is polled by htmx to provide real-time updates of vector sync processing
+    status without requiring a full page refresh.
+
+    Requires authentication via session cookie (redirects to oauth_login route if not authenticated).
+
+    Args:
+        request: Starlette request object
+
+    Returns:
+        HTML response with vector sync status table fragment
+    """
+    processing_status = await _get_processing_status(request)
+
+    # If vector sync is disabled or unavailable, return empty fragment
+    if not processing_status:
+        return HTMLResponse(
+            """
+            <div id="vector-sync-status" hx-get="/app/vector-sync/status" hx-trigger="every 10s" hx-swap="innerHTML">
+                <p style="color: #999;">Vector sync not available</p>
+            </div>
+            """
+        )
+
+    indexed_count = processing_status["indexed_count"]
+    pending_count = processing_status["pending_count"]
+    status = processing_status["status"]
+
+    # Format numbers with commas for readability
+    indexed_count_str = f"{indexed_count:,}"
+    pending_count_str = f"{pending_count:,}"
+
+    # Status badge color and text
+    if status == "syncing":
+        status_badge = (
+            '<span style="color: #ff9800; font-weight: bold;">⟳ Syncing</span>'
+        )
+    else:
+        status_badge = '<span style="color: #4caf50; font-weight: bold;">✓ Idle</span>'
+
+    # Return inner content only (container div is in initial page render)
+    html = f"""
+    <h2>Vector Sync Status</h2>
+    <table>
+        <tr>
+            <td><strong>Indexed Documents</strong></td>
+            <td>{indexed_count_str}</td>
+        </tr>
+        <tr>
+            <td><strong>Pending Documents</strong></td>
+            <td>{pending_count_str}</td>
+        </tr>
+        <tr>
+            <td><strong>Status</strong></td>
+            <td>{status_badge}</td>
+        </tr>
+    </table>
+    """
+
+    return HTMLResponse(html)
+
+
 async def _get_userinfo_endpoint(oauth_ctx: dict[str, Any]) -> str | None:
     """Get the correct userinfo endpoint based on OAuth mode.
 
@@ -224,6 +409,22 @@ async def user_info_html(request: Request) -> HTMLResponse:
     """
     user_context = await _get_user_info(request)
 
+    # Get vector sync processing status
+    processing_status = await _get_processing_status(request)
+
+    # Check if user is admin (for Webhooks tab)
+    is_admin = False
+    try:
+        from nextcloud_mcp_server.auth.permissions import is_nextcloud_admin
+
+        # Get authenticated HTTP client
+        http_client = await _get_authenticated_client_for_userinfo(request)
+        is_admin = await is_nextcloud_admin(request, http_client)
+        await http_client.aclose()
+    except Exception as e:
+        logger.warning(f"Failed to check admin status: {e}")
+        # Default to not admin if check fails
+
     # Check for error
     if "error" in user_context and user_context["error"] != "":
         # Get login URL dynamically
@@ -288,6 +489,16 @@ async def user_info_html(request: Request) -> HTMLResponse:
             str(request.url_for("oauth_logout")) if oauth_ctx else "/oauth/logout"
         )
 
+    # Get Nextcloud host for generating links to apps (used by viz tab)
+    # Use public issuer URL if available (for browser-accessible links),
+    # otherwise fall back to NEXTCLOUD_HOST from settings
+    from nextcloud_mcp_server.config import get_settings
+
+    settings = get_settings()
+    nextcloud_host_for_links = (
+        os.getenv("NEXTCLOUD_PUBLIC_ISSUER_URL") or settings.nextcloud_host
+    )
+
     # Build host info HTML (BasicAuth only)
     host_info_html = ""
     if auth_mode == "basic":
@@ -371,6 +582,17 @@ async def user_info_html(request: Request) -> HTMLResponse:
             </div>
             """
 
+    # Build vector sync status HTML (with htmx auto-refresh)
+    vector_status_html = ""
+    if processing_status:
+        # Use htmx to load and auto-refresh the status fragment
+        # Container div stays stable, only inner content updates every 10s
+        vector_status_html = """
+            <div id="vector-sync-status" hx-get="/app/vector-sync/status" hx-trigger="load, every 10s" hx-swap="innerHTML">
+                <p style="color: #999;">Loading vector sync status...</p>
+            </div>
+        """
+
     # Build IdP profile HTML
     idp_profile_html = ""
     if "idp_profile" in user_context:
@@ -395,17 +617,182 @@ async def user_info_html(request: Request) -> HTMLResponse:
         <div class="warning">{user_context["idp_profile_error"]}</div>
         """
 
+    # Build user info tab content
+    user_info_tab_html = f"""
+        <h2>Authentication</h2>
+        <table>
+            <tr>
+                <td><strong>Username</strong></td>
+                <td>{username}</td>
+            </tr>
+            <tr>
+                <td><strong>Authentication Mode</strong></td>
+                <td><span class="badge badge-{auth_mode}">{auth_mode}</span></td>
+            </tr>
+        </table>
+
+        {host_info_html}
+        {session_info_html}
+        {idp_profile_html}
+    """
+
+    # Determine which tabs to show
+    show_vector_sync_tab = processing_status is not None
+    show_webhooks_tab = is_admin
+
+    # Build vector sync tab content (only if enabled)
+    vector_sync_tab_html = ""
+    if show_vector_sync_tab:
+        vector_sync_tab_html = vector_status_html
+
+    # Build webhooks tab content (only if admin)
+    webhooks_tab_html = ""
+    if show_webhooks_tab:
+        webhooks_tab_html = """
+            <div hx-get="/app/webhooks" hx-trigger="load" hx-swap="outerHTML">
+                <p style="color: #999;">Loading webhook management...</p>
+            </div>
+        """
+
     html_content = f"""
     <!DOCTYPE html>
     <html lang="en">
     <head>
         <meta charset="UTF-8">
         <meta name="viewport" content="width=device-width, initial-scale=1.0">
-        <title>User Info - Nextcloud MCP Server</title>
+        <title>Nextcloud MCP Server</title>
+
+        <!-- htmx for dynamic loading -->
+        <script src="https://unpkg.com/htmx.org@1.9.10"></script>
+
+        <!-- Alpine.js for tab state management -->
+        <script defer src="https://cdn.jsdelivr.net/npm/alpinejs@3.x.x/dist/cdn.min.js"></script>
+
+        <!-- Plotly.js for vector visualization -->
+        <script src="https://cdn.plot.ly/plotly-2.27.0.min.js"></script>
+
+        <!-- Vector visualization app (Alpine.js component) -->
+        <script>
+            function vizApp() {{
+                return {{
+                    query: '',
+                    algorithm: 'hybrid',
+                    showAdvanced: false,
+                    docTypes: [''],  // Default to "All Types"
+                    limit: 50,
+                    scoreThreshold: 0.7,
+                    semanticWeight: 0.5,
+                    keywordWeight: 0.3,
+                    fuzzyWeight: 0.2,
+                    loading: false,
+                    results: [],
+
+                    async executeSearch() {{
+                        this.loading = true;
+                        this.results = [];
+
+                        try {{
+                            const params = new URLSearchParams({{
+                                query: this.query,
+                                algorithm: this.algorithm,
+                                limit: this.limit,
+                                score_threshold: this.scoreThreshold,
+                                semantic_weight: this.semanticWeight,
+                                keyword_weight: this.keywordWeight,
+                                fuzzy_weight: this.fuzzyWeight,
+                            }});
+
+                            // Add doc_types parameter (filter out empty string for "All Types")
+                            const selectedTypes = this.docTypes.filter(t => t !== '');
+                            if (selectedTypes.length > 0) {{
+                                params.append('doc_types', selectedTypes.join(','));
+                            }}
+
+                            const response = await fetch(`/app/vector-viz/search?${{params}}`);
+                            const data = await response.json();
+
+                            if (data.success) {{
+                                this.results = data.results;
+                                this.renderPlot(data.coordinates_2d, data.results);
+                            }} else {{
+                                alert('Search failed: ' + data.error);
+                            }}
+                        }} catch (error) {{
+                            alert('Error: ' + error.message);
+                        }} finally {{
+                            this.loading = false;
+                        }}
+                    }},
+
+                    renderPlot(coordinates, results) {{
+                        // Calculate score range for auto-scaling
+                        const scores = results.map(r => r.score);
+                        const minScore = Math.min(...scores);
+                        const maxScore = Math.max(...scores);
+
+                        const trace = {{
+                            x: coordinates.map(c => c[0]),
+                            y: coordinates.map(c => c[1]),
+                            mode: 'markers',
+                            type: 'scatter',
+                            text: results.map(r => `${{r.title}}<br>Score: ${{r.score.toFixed(3)}}`),
+                            marker: {{
+                                // Multi-channel encoding: size + opacity + color for visual hierarchy
+                                // Power scaling (score^2) amplifies visual differences dramatically
+                                // score=0.0 → 6px, score=0.5 → 9.5px, score=1.0 → 20px
+                                size: results.map(r => 6 + (Math.pow(r.score, 2) * 14)),
+                                // Linear opacity scaling (0.2-1.0 range keeps all points visible)
+                                opacity: results.map(r => 0.2 + (r.score * 0.8)),
+                                // Color gradient shows score
+                                color: scores,
+                                colorscale: 'Viridis',
+                                showscale: true,
+                                colorbar: {{ title: 'Relative Score' }},
+                                // Scores are normalized 0-1 within result set
+                                cmin: 0,
+                                cmax: 1
+                            }}
+                        }};
+
+                        const layout = {{
+                            title: `Vector Space (PCA 2D) - ${{results.length}} results`,
+                            xaxis: {{ title: 'PC1' }},
+                            yaxis: {{ title: 'PC2' }},
+                            hovermode: 'closest',
+                            height: 600
+                        }};
+
+                        Plotly.newPlot('viz-plot', [trace], layout);
+                    }},
+
+                    getNextcloudUrl(result) {{
+                        // Generate Nextcloud URL based on document type
+                        // Use the actual Nextcloud host (port 8080), not the MCP server
+                        const baseUrl = '{nextcloud_host_for_links}';
+
+                        switch (result.doc_type) {{
+                            case 'note':
+                                return `${{baseUrl}}/apps/notes/note/${{result.id}}`;
+                            case 'file':
+                                return `${{baseUrl}}/apps/files/?fileId=${{result.id}}`;
+                            case 'calendar':
+                                return `${{baseUrl}}/apps/calendar`;
+                            case 'contact':
+                                return `${{baseUrl}}/apps/contacts`;
+                            case 'deck':
+                                return `${{baseUrl}}/apps/deck`;
+                            default:
+                                return `${{baseUrl}}`;
+                        }}
+                    }}
+                }}
+            }}
+        </script>
+
         <style>
             body {{
                 font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
-                max-width: 800px;
+                max-width: 900px;
                 margin: 50px auto;
                 padding: 20px;
                 background-color: #f5f5f5;
@@ -415,6 +802,7 @@ async def user_info_html(request: Request) -> HTMLResponse:
                 border-radius: 8px;
                 padding: 30px;
                 box-shadow: 0 2px 4px rgba(0,0,0,0.1);
+                min-height: calc(100vh - 200px);
             }}
             h1 {{
                 color: #0082c9;
@@ -424,10 +812,51 @@ async def user_info_html(request: Request) -> HTMLResponse:
             }}
             h2 {{
                 color: #333;
-                margin-top: 30px;
+                margin-top: 20px;
                 border-bottom: 1px solid #e0e0e0;
                 padding-bottom: 5px;
             }}
+
+            /* Tab navigation */
+            .tabs {{
+                display: flex;
+                gap: 0;
+                margin: 20px 0 0 0;
+                border-bottom: 2px solid #e0e0e0;
+            }}
+            .tab {{
+                padding: 12px 24px;
+                cursor: pointer;
+                background: transparent;
+                border: none;
+                font-size: 14px;
+                font-weight: 500;
+                color: #666;
+                border-bottom: 2px solid transparent;
+                margin-bottom: -2px;
+                transition: all 0.2s;
+            }}
+            .tab:hover {{
+                color: #0082c9;
+                background-color: #f5f5f5;
+            }}
+            .tab.active {{
+                color: #0082c9;
+                border-bottom-color: #0082c9;
+            }}
+
+            /* Tab content - use grid to overlay panes */
+            .tab-content {{
+                padding: 20px 0;
+                display: grid;
+            }}
+
+            /* Tab panes - all occupy the same grid cell to overlay */
+            .tab-pane {{
+                grid-area: 1 / 1;
+            }}
+
+            /* Tables */
             table {{
                 width: 100%;
                 border-collapse: collapse;
@@ -447,6 +876,8 @@ async def user_info_html(request: Request) -> HTMLResponse:
                 border-radius: 3px;
                 font-family: 'Courier New', monospace;
             }}
+
+            /* Badges */
             .badge {{
                 display: inline-block;
                 padding: 3px 8px;
@@ -463,6 +894,8 @@ async def user_info_html(request: Request) -> HTMLResponse:
                 background-color: #2196f3;
                 color: white;
             }}
+
+            /* Messages */
             .warning {{
                 background-color: #fff3cd;
                 border-left: 4px solid #ffc107;
@@ -470,11 +903,15 @@ async def user_info_html(request: Request) -> HTMLResponse:
                 margin: 15px 0;
                 color: #856404;
             }}
-            .logout {{
-                margin-top: 30px;
-                padding-top: 20px;
-                border-top: 1px solid #e0e0e0;
+            .info-message {{
+                background-color: #e3f2fd;
+                border-left: 4px solid #2196f3;
+                padding: 15px;
+                margin: 15px 0;
+                color: #1565c0;
             }}
+
+            /* Buttons */
             .button {{
                 display: inline-block;
                 padding: 10px 20px;
@@ -483,33 +920,138 @@ async def user_info_html(request: Request) -> HTMLResponse:
                 text-decoration: none;
                 border-radius: 4px;
                 transition: background-color 0.3s;
+                border: none;
+                cursor: pointer;
+                font-size: 14px;
             }}
             .button:hover {{
                 background-color: #b71c1c;
             }}
+            .button-primary {{
+                background-color: #0082c9;
+            }}
+            .button-primary:hover {{
+                background-color: #006ba3;
+            }}
+
+            /* Logout section */
+            .logout {{
+                margin-top: 30px;
+                padding-top: 20px;
+                border-top: 1px solid #e0e0e0;
+            }}
+
+            /* Smooth htmx content swaps */
+            .htmx-swapping {{
+                opacity: 0;
+                transition: opacity 200ms ease-out;
+            }}
+
+            /* Smooth htmx content settling */
+            .htmx-settling {{
+                opacity: 1;
+                transition: opacity 200ms ease-in;
+            }}
         </style>
     </head>
     <body>
-        <div class="container">
-            <h1>Nextcloud MCP Server - User Info</h1>
+        <div class="container" x-data="{{ activeTab: 'user-info' }}">
+            <h1>Nextcloud MCP Server</h1>
 
-            <h2>Authentication</h2>
-            <table>
-                <tr>
-                    <td><strong>Username</strong></td>
-                    <td>{username}</td>
-                </tr>
-                <tr>
-                    <td><strong>Authentication Mode</strong></td>
-                    <td><span class="badge badge-{auth_mode}">{auth_mode}</span></td>
-                </tr>
-            </table>
+            <!-- Tab Navigation -->
+            <div class="tabs">
+                <button
+                    class="tab"
+                    :class="activeTab === 'user-info' ? 'active' : ''"
+                    @click="activeTab = 'user-info'">
+                    User Info
+                </button>
+                {
+        ""
+        if not show_vector_sync_tab
+        else '''
+                <button
+                    class="tab"
+                    :class="activeTab === 'vector-sync' ? 'active' : ''"
+                    @click="activeTab = 'vector-sync'">
+                    Vector Sync
+                </button>
+                '''
+    }
+                {
+        ""
+        if not show_vector_sync_tab
+        else '''
+                <button
+                    class="tab"
+                    :class="activeTab === 'vector-viz' ? 'active' : ''"
+                    @click="activeTab = 'vector-viz'">
+                    Vector Viz
+                </button>
+                '''
+    }
+                {
+        ""
+        if not show_webhooks_tab
+        else '''
+                <button
+                    class="tab"
+                    :class="activeTab === 'webhooks' ? 'active' : ''"
+                    @click="activeTab = 'webhooks'">
+                    Webhooks
+                </button>
+                '''
+    }
+            </div>
 
-            {host_info_html}
-            {session_info_html}
-            {idp_profile_html}
+            <!-- Tab Content -->
+            <div class="tab-content">
+                <!-- User Info Tab -->
+                <div class="tab-pane" x-show="activeTab === 'user-info'" x-transition.opacity.duration.150ms>
+                    {user_info_tab_html}
+                </div>
 
-            {f'<div class="logout"><a href="{logout_url}" class="button">Logout</a></div>' if auth_mode == "oauth" else ""}
+                {
+        ""
+        if not show_vector_sync_tab
+        else f'''
+                <!-- Vector Sync Tab -->
+                <div class="tab-pane" x-show="activeTab === 'vector-sync'" x-transition.opacity.duration.150ms>
+                    {vector_sync_tab_html}
+                </div>
+                '''
+    }
+
+                {
+        ""
+        if not show_vector_sync_tab
+        else '''
+                <!-- Vector Viz Tab -->
+                <div class="tab-pane" x-show="activeTab === 'vector-viz'" x-transition.opacity.duration.150ms>
+                    <div hx-get="/app/vector-viz" hx-trigger="load" hx-swap="outerHTML">
+                        <p style="color: #999;">Loading vector visualization...</p>
+                    </div>
+                </div>
+                '''
+    }
+
+                {
+        ""
+        if not show_webhooks_tab
+        else f'''
+                <!-- Webhooks Tab (admin-only, loaded dynamically) -->
+                <div class="tab-pane" x-show="activeTab === 'webhooks'" x-transition.opacity.duration.150ms>
+                    {webhooks_tab_html}
+                </div>
+                '''
+    }
+            </div>
+
+            {
+        f'<div class="logout"><a href="{logout_url}" class="button">Logout</a></div>'
+        if auth_mode == "oauth"
+        else ""
+    }
         </div>
     </body>
     </html>

nextcloud_mcp_server/auth/viz_routes.py

@@ -0,0 +1,612 @@
+"""Vector visualization routes for testing search algorithms.
+
+Provides a web UI for users to test different search algorithms on their own
+indexed documents and visualize results in 2D space using PCA.
+
+All processing happens server-side following ADR-012:
+- Search execution via shared search/algorithms.py
+- PCA dimensionality reduction (768-dim → 2D)
+- Only 2D coordinates + metadata sent to client
+- Bandwidth-efficient (2 floats per doc vs 768)
+"""
+
+import logging
+import time
+
+import numpy as np
+from starlette.authentication import requires
+from starlette.requests import Request
+from starlette.responses import HTMLResponse, JSONResponse
+
+from nextcloud_mcp_server.config import get_settings
+from nextcloud_mcp_server.search import (
+    FuzzySearchAlgorithm,
+    HybridSearchAlgorithm,
+    KeywordSearchAlgorithm,
+    SemanticSearchAlgorithm,
+)
+from nextcloud_mcp_server.vector.pca import PCA
+from nextcloud_mcp_server.vector.qdrant_client import get_qdrant_client
+
+logger = logging.getLogger(__name__)
+
+
+@requires("authenticated", redirect="oauth_login")
+async def vector_visualization_html(request: Request) -> HTMLResponse:
+    """Vector visualization page with search controls and interactive plot.
+
+    Provides UI for testing search algorithms with real-time visualization.
+    Requires vector sync to be enabled.
+
+    Args:
+        request: Starlette request object
+
+    Returns:
+        HTML page with search interface
+    """
+    settings = get_settings()
+
+    if not settings.vector_sync_enabled:
+        return HTMLResponse(
+            """
+            <div>
+                <h2>Vector Visualization</h2>
+                <div style="padding: 20px; background: #fff3cd; border: 1px solid #ffc107; border-radius: 4px;">
+                    Vector sync is not enabled. Set VECTOR_SYNC_ENABLED=true to use this feature.
+                </div>
+            </div>
+            """
+        )
+
+    # Get user info from auth context
+    username = (
+        request.user.display_name
+        if hasattr(request.user, "display_name")
+        else "unknown"
+    )
+
+    html_content = f"""
+        <style>
+            .viz-card {{
+                background: white;
+                border-radius: 8px;
+                padding: 20px;
+                margin-bottom: 20px;
+                box-shadow: 0 2px 4px rgba(0,0,0,0.1);
+            }}
+            .viz-controls {{
+                margin-bottom: 20px;
+            }}
+            .viz-control-row {{
+                display: grid;
+                grid-template-columns: 2fr 1fr auto;
+                gap: 12px;
+                margin-bottom: 12px;
+                align-items: end;
+            }}
+            .viz-control-group {{
+                margin-bottom: 15px;
+            }}
+            .viz-control-group label {{
+                display: block;
+                margin-bottom: 5px;
+                font-weight: 500;
+                color: #333;
+            }}
+            .viz-control-group input[type="text"],
+            .viz-control-group input[type="number"],
+            .viz-control-group select {{
+                width: 100%;
+                padding: 8px 12px;
+                border: 1px solid #ddd;
+                border-radius: 4px;
+                font-size: 14px;
+            }}
+            .viz-control-group input[type="range"] {{
+                width: 100%;
+            }}
+            .viz-control-group select[multiple] {{
+                min-height: 100px;
+            }}
+            .viz-weight-display {{
+                display: inline-block;
+                min-width: 40px;
+                text-align: right;
+                color: #666;
+            }}
+            .viz-btn {{
+                background: #0066cc;
+                color: white;
+                border: none;
+                padding: 10px 20px;
+                border-radius: 4px;
+                cursor: pointer;
+                font-size: 14px;
+                font-weight: 500;
+            }}
+            .viz-btn:hover {{
+                background: #0052a3;
+            }}
+            .viz-btn-secondary {{
+                background: #6c757d;
+                color: white;
+                border: none;
+                padding: 6px 12px;
+                border-radius: 4px;
+                cursor: pointer;
+                font-size: 13px;
+                margin-bottom: 12px;
+            }}
+            .viz-btn-secondary:hover {{
+                background: #5a6268;
+            }}
+            #viz-plot-container {{
+                width: 100%;
+                height: 600px;
+                position: relative;
+            }}
+            #viz-plot {{
+                width: 100%;
+                height: 100%;
+            }}
+            .viz-loading {{
+                text-align: center;
+                padding: 40px;
+                color: #666;
+            }}
+            .viz-loading-overlay {{
+                position: absolute;
+                inset: 0;
+                display: flex;
+                align-items: center;
+                justify-content: center;
+                background: white;
+                color: #666;
+            }}
+            .viz-no-results {{
+                text-align: center;
+                padding: 40px;
+                color: #666;
+                font-style: italic;
+            }}
+            .viz-advanced-section {{
+                margin-top: 16px;
+                padding: 16px;
+                background: #f8f9fa;
+                border-radius: 4px;
+                border: 1px solid #dee2e6;
+            }}
+            .viz-advanced-grid {{
+                display: grid;
+                grid-template-columns: 1fr 1fr;
+                gap: 20px;
+            }}
+            .viz-info-box {{
+                background: #e3f2fd;
+                border-left: 4px solid #2196f3;
+                padding: 12px;
+                margin-bottom: 20px;
+                font-size: 14px;
+            }}
+        </style>
+
+        <div x-data="vizApp()">
+            <div class="viz-card">
+                <h2>Vector Visualization</h2>
+                <div class="viz-info-box">
+                    Testing search algorithms on your indexed documents. User: <strong>{username}</strong>
+                </div>
+
+                <form @submit.prevent="executeSearch">
+                    <div class="viz-controls">
+                        <!-- Main Controls -->
+                        <div class="viz-control-group">
+                            <label>Search Query</label>
+                            <input type="text" x-model="query" placeholder="Enter search query..." required />
+                        </div>
+
+                        <div class="viz-control-row">
+                            <div class="viz-control-group" style="margin-bottom: 0;">
+                                <label>Algorithm</label>
+                                <select x-model="algorithm">
+                                    <option value="semantic">Semantic (Vector Similarity)</option>
+                                    <option value="keyword">Keyword (Token Matching)</option>
+                                    <option value="fuzzy">Fuzzy (Character Overlap)</option>
+                                    <option value="hybrid" selected>Hybrid (RRF Fusion)</option>
+                                </select>
+                            </div>
+
+                            <div style="display: flex; align-items: flex-end;">
+                                <button type="submit" class="viz-btn" style="width: 100%;">Search & Visualize</button>
+                            </div>
+
+                            <div style="display: flex; align-items: flex-end;">
+                                <button type="button" class="viz-btn-secondary" @click="showAdvanced = !showAdvanced" style="white-space: nowrap;">
+                                    <span x-text="showAdvanced ? 'Hide Advanced' : 'Advanced'"></span>
+                                </button>
+                            </div>
+                        </div>
+
+                        <!-- Advanced Options (Collapsible) -->
+                        <div class="viz-advanced-section" x-show="showAdvanced" x-transition.opacity.duration.200ms>
+                            <h3 style="margin-top: 0; margin-bottom: 16px; font-size: 16px;">Advanced Options</h3>
+
+                            <div class="viz-advanced-grid">
+                                <div class="viz-control-group">
+                                    <label>Document Types</label>
+                                    <select x-model="docTypes" multiple>
+                                        <option value="">All Types (cross-app search)</option>
+                                        <option value="note">Notes</option>
+                                        <option value="file">Files</option>
+                                        <option value="calendar">Calendar Events</option>
+                                        <option value="contact">Contacts</option>
+                                        <option value="deck">Deck Cards</option>
+                                    </select>
+                                    <small style="color: #666; display: block; margin-top: 4px;">
+                                        Hold Ctrl/Cmd to select multiple
+                                    </small>
+                                </div>
+
+                                <div>
+                                    <div class="viz-control-group">
+                                        <label>Score Threshold (Semantic/Hybrid)</label>
+                                        <input type="number" x-model.number="scoreThreshold" min="0" max="1" step="0.1" />
+                                    </div>
+
+                                    <div class="viz-control-group">
+                                        <label>Result Limit</label>
+                                        <input type="number" x-model.number="limit" min="1" max="100" />
+                                    </div>
+                                </div>
+                            </div>
+
+                            <!-- Hybrid Weights (only when hybrid selected) -->
+                            <div x-show="algorithm === 'hybrid'" style="margin-top: 16px; padding: 12px; background: #e9ecef; border-radius: 4px;">
+                                <label style="margin-bottom: 12px; display: block;">Hybrid Algorithm Weights</label>
+
+                                <div style="margin-bottom: 8px;">
+                                    <label style="display: inline-block; width: 100px; font-weight: normal;">Semantic:</label>
+                                    <input type="range" x-model.number="semanticWeight" min="0" max="1" step="0.1" style="width: 200px; display: inline-block;">
+                                    <span class="viz-weight-display" x-text="semanticWeight.toFixed(1)"></span>
+                                </div>
+                                <div style="margin-bottom: 8px;">
+                                    <label style="display: inline-block; width: 100px; font-weight: normal;">Keyword:</label>
+                                    <input type="range" x-model.number="keywordWeight" min="0" max="1" step="0.1" style="width: 200px; display: inline-block;">
+                                    <span class="viz-weight-display" x-text="keywordWeight.toFixed(1)"></span>
+                                </div>
+                                <div>
+                                    <label style="display: inline-block; width: 100px; font-weight: normal;">Fuzzy:</label>
+                                    <input type="range" x-model.number="fuzzyWeight" min="0" max="1" step="0.1" style="width: 200px; display: inline-block;">
+                                    <span class="viz-weight-display" x-text="fuzzyWeight.toFixed(1)"></span>
+                                </div>
+                            </div>
+                        </div>
+                    </div>
+                </form>
+            </div>
+
+            <div class="viz-card">
+                <div id="viz-plot-container">
+                    <div x-show="loading" class="viz-loading-overlay" x-transition.opacity.duration.200ms>
+                        Executing search and computing PCA projection...
+                    </div>
+                    <div id="viz-plot" x-show="!loading" x-transition.opacity.duration.200ms></div>
+                </div>
+            </div>
+
+            <div class="viz-card">
+                <h3>Search Results (<span x-text="loading ? '...' : results.length"></span>)</h3>
+
+                <div x-show="loading" class="viz-loading" x-transition.opacity.duration.200ms>
+                    Loading results...
+                </div>
+
+                <div x-show="!loading && results.length === 0" class="viz-no-results" x-transition.opacity.duration.200ms>
+                    No results found. Try a different query or adjust your search parameters.
+                </div>
+
+                <template x-if="!loading && results.length > 0">
+                    <div x-transition.opacity.duration.200ms>
+                        <template x-for="result in results" :key="result.id">
+                            <div style="padding: 12px; border-bottom: 1px solid #eee;">
+                                <a :href="getNextcloudUrl(result)" target="_blank" style="font-weight: 500; color: #0066cc; text-decoration: none;">
+                                    <span x-text="result.title"></span>
+                                </a>
+                                <div style="font-size: 14px; color: #666; margin-top: 4px;" x-text="result.excerpt"></div>
+                                <div style="font-size: 12px; color: #999; margin-top: 4px;">
+                                    Score: <span x-text="result.score.toFixed(3)"></span> |
+                                    Type: <span x-text="result.doc_type"></span>
+                                </div>
+                            </div>
+                        </template>
+                    </div>
+                </template>
+            </div>
+        </div>
+    """
+
+    return HTMLResponse(content=html_content)
+
+
+@requires("authenticated", redirect="oauth_login")
+async def vector_visualization_search(request: Request) -> JSONResponse:
+    """Execute server-side search and return 2D coordinates + results.
+
+    All processing happens server-side:
+    1. Execute search via shared algorithm module
+    2. Fetch matching vectors from Qdrant
+    3. Apply PCA reduction (768-dim → 2D)
+    4. Return coordinates + metadata only
+
+    Args:
+        request: Starlette request with query parameters
+
+    Returns:
+        JSON response with coordinates_2d and results
+    """
+    settings = get_settings()
+
+    if not settings.vector_sync_enabled:
+        return JSONResponse(
+            {"success": False, "error": "Vector sync not enabled"},
+            status_code=400,
+        )
+
+    # Get user info from auth context
+    username = (
+        request.user.display_name if hasattr(request.user, "display_name") else None
+    )
+
+    if not username:
+        return JSONResponse(
+            {"success": False, "error": "User not authenticated"},
+            status_code=401,
+        )
+
+    # Parse query parameters
+    query = request.query_params.get("query", "")
+    algorithm = request.query_params.get("algorithm", "hybrid")
+    limit = int(request.query_params.get("limit", "50"))
+    score_threshold = float(request.query_params.get("score_threshold", "0.7"))
+    semantic_weight = float(request.query_params.get("semantic_weight", "0.5"))
+    keyword_weight = float(request.query_params.get("keyword_weight", "0.3"))
+    fuzzy_weight = float(request.query_params.get("fuzzy_weight", "0.2"))
+
+    # Parse doc_types (comma-separated list, None = all types)
+    doc_types_param = request.query_params.get("doc_types", "")
+    doc_types = doc_types_param.split(",") if doc_types_param else None
+
+    logger.info(
+        f"Viz search: user={username}, query='{query}', "
+        f"algorithm={algorithm}, limit={limit}, doc_types={doc_types}"
+    )
+
+    try:
+        # Start total request timer
+        request_start = time.perf_counter()
+        # Get authenticated HTTP client from session
+        # In BasicAuth mode: uses username/password from session
+        # In OAuth mode: uses access token from session
+        from nextcloud_mcp_server.auth.userinfo_routes import (
+            _get_authenticated_client_for_userinfo,
+        )
+
+        async with await _get_authenticated_client_for_userinfo(request) as http_client:  # noqa: F841
+            # Create search algorithm (no client needed - verification removed)
+            if algorithm == "semantic":
+                search_algo = SemanticSearchAlgorithm(score_threshold=score_threshold)
+            elif algorithm == "keyword":
+                search_algo = KeywordSearchAlgorithm()
+            elif algorithm == "fuzzy":
+                search_algo = FuzzySearchAlgorithm()
+            elif algorithm == "hybrid":
+                search_algo = HybridSearchAlgorithm(
+                    semantic_weight=semantic_weight,
+                    keyword_weight=keyword_weight,
+                    fuzzy_weight=fuzzy_weight,
+                )
+            else:
+                return JSONResponse(
+                    {"success": False, "error": f"Unknown algorithm: {algorithm}"},
+                    status_code=400,
+                )
+
+            # Execute search (supports cross-app when doc_types=None)
+            # Get unverified results with buffer for filtering
+            search_start = time.perf_counter()
+            all_results = []
+            if doc_types is None or len(doc_types) == 0:
+                # Cross-app search - search all indexed types
+                unverified_results = await search_algo.search(
+                    query=query,
+                    user_id=username,
+                    limit=limit * 2,  # Buffer for verification filtering
+                    doc_type=None,  # Search all types
+                    score_threshold=score_threshold,
+                )
+                all_results.extend(unverified_results)
+            else:
+                # Search each document type and combine
+                for doc_type in doc_types:
+                    unverified_results = await search_algo.search(
+                        query=query,
+                        user_id=username,
+                        limit=limit * 2,  # Buffer for verification filtering
+                        doc_type=doc_type,
+                        score_threshold=score_threshold,
+                    )
+                    all_results.extend(unverified_results)
+                # Sort by score before verification
+                all_results.sort(key=lambda r: r.score, reverse=True)
+
+            # No verification needed for visualization - we only need Qdrant metadata
+            # (title, excerpt, doc_type) which is already in search results.
+            # Verification is only needed for sampling (LLM needs full content).
+            search_results = all_results[:limit]
+            search_duration = time.perf_counter() - search_start
+
+        # Normalize scores relative to this result set for better visualization
+        # (best result = 1.0, worst result = 0.0 within THIS result set)
+        # This makes visual encoding meaningful regardless of RRF normalization
+        if search_results:
+            scores = [r.score for r in search_results]
+            min_score, max_score = min(scores), max(scores)
+            score_range = max_score - min_score if max_score > min_score else 1.0
+
+            logger.info(
+                f"Normalizing scores for viz: original range [{min_score:.3f}, {max_score:.3f}] "
+                f"→ [0.0, 1.0]"
+            )
+
+            # Rescale each result's score to 0-1 within this result set
+            for r in search_results:
+                r.score = (r.score - min_score) / score_range
+
+        if not search_results:
+            return JSONResponse(
+                {
+                    "success": True,
+                    "results": [],
+                    "coordinates_2d": [],
+                    "message": "No results found",
+                }
+            )
+
+        # Fetch vectors for matching results from Qdrant
+        vector_fetch_start = time.perf_counter()
+        qdrant_client = await get_qdrant_client()
+        doc_ids = [r.id for r in search_results]
+
+        # Retrieve vectors for the matching documents
+        from qdrant_client.models import FieldCondition, Filter, MatchAny
+
+        points_response = await qdrant_client.scroll(
+            collection_name=settings.get_collection_name(),
+            scroll_filter=Filter(
+                must=[
+                    FieldCondition(
+                        key="doc_id",
+                        match=MatchAny(any=[str(doc_id) for doc_id in doc_ids]),
+                    ),
+                    FieldCondition(
+                        key="user_id",
+                        match={"value": username},
+                    ),
+                ]
+            ),
+            limit=len(doc_ids) * 2,  # Account for multiple chunks per doc
+            with_vectors=True,
+            with_payload=["doc_id"],  # Need doc_id to map vectors to results
+        )
+
+        points = points_response[0]
+
+        if not points:
+            return JSONResponse(
+                {
+                    "success": True,
+                    "results": [],
+                    "coordinates_2d": [],
+                    "message": "No vectors found for results",
+                }
+            )
+
+        # Extract vectors
+        vectors = np.array([p.vector for p in points if p.vector is not None])
+        vector_fetch_duration = time.perf_counter() - vector_fetch_start
+
+        if len(vectors) < 2:
+            # Not enough points for PCA
+            return JSONResponse(
+                {
+                    "success": True,
+                    "results": [
+                        {
+                            "id": r.id,
+                            "doc_type": r.doc_type,
+                            "title": r.title,
+                            "excerpt": r.excerpt,
+                            "score": r.score,
+                        }
+                        for r in search_results
+                    ],
+                    "coordinates_2d": [[0, 0]] * len(search_results),
+                    "message": "Not enough vectors for PCA",
+                }
+            )
+
+        # Apply PCA dimensionality reduction (768-dim → 2D)
+        pca_start = time.perf_counter()
+        pca = PCA(n_components=2)
+        coords_2d = pca.fit_transform(vectors)
+        pca_duration = time.perf_counter() - pca_start
+
+        # After fit, these attributes are guaranteed to be set
+        assert pca.explained_variance_ratio_ is not None
+
+        logger.info(
+            f"PCA explained variance: PC1={pca.explained_variance_ratio_[0]:.3f}, "
+            f"PC2={pca.explained_variance_ratio_[1]:.3f}"
+        )
+
+        # Map results to coordinates (use first chunk per document)
+        result_coords = []
+        seen_doc_ids = set()
+
+        for point, coord in zip(points, coords_2d):
+            if point.payload:
+                doc_id = int(point.payload.get("doc_id", 0))
+                if doc_id not in seen_doc_ids and doc_id in doc_ids:
+                    seen_doc_ids.add(doc_id)
+                    result_coords.append(coord.tolist())
+
+        # Build response
+        response_results = [
+            {
+                "id": r.id,
+                "doc_type": r.doc_type,
+                "title": r.title,
+                "excerpt": r.excerpt,
+                "score": r.score,
+            }
+            for r in search_results
+        ]
+
+        # Calculate total request duration
+        total_duration = time.perf_counter() - request_start
+
+        # Log comprehensive timing metrics
+        logger.info(
+            f"Viz search timing: total={total_duration * 1000:.1f}ms, "
+            f"search={search_duration * 1000:.1f}ms ({search_duration / total_duration * 100:.1f}%), "
+            f"vector_fetch={vector_fetch_duration * 1000:.1f}ms ({vector_fetch_duration / total_duration * 100:.1f}%), "
+            f"pca={pca_duration * 1000:.1f}ms ({pca_duration / total_duration * 100:.1f}%), "
+            f"results={len(search_results)}, vectors={len(vectors)}"
+        )
+
+        return JSONResponse(
+            {
+                "success": True,
+                "results": response_results,
+                "coordinates_2d": result_coords[: len(search_results)],
+                "pca_variance": {
+                    "pc1": float(pca.explained_variance_ratio_[0]),
+                    "pc2": float(pca.explained_variance_ratio_[1]),
+                },
+                "timing": {
+                    "total_ms": round(total_duration * 1000, 2),
+                    "search_ms": round(search_duration * 1000, 2),
+                    "vector_fetch_ms": round(vector_fetch_duration * 1000, 2),
+                    "pca_ms": round(pca_duration * 1000, 2),
+                    "num_results": len(search_results),
+                    "num_vectors": len(vectors),
+                },
+            }
+        )
+
+    except Exception as e:
+        logger.error(f"Viz search error: {e}", exc_info=True)
+        return JSONResponse(
+            {"success": False, "error": str(e)},
+            status_code=500,
+        )

nextcloud_mcp_server/auth/webhook_routes.py

@@ -0,0 +1,540 @@
+"""Webhook management routes for admin UI.
+
+Provides browser-based endpoints for admin users to manage webhook configurations
+using preset templates. Only accessible to Nextcloud administrators.
+"""
+
+import logging
+import os
+
+import httpx
+from starlette.authentication import requires
+from starlette.requests import Request
+from starlette.responses import HTMLResponse
+
+from nextcloud_mcp_server.auth.permissions import is_nextcloud_admin
+from nextcloud_mcp_server.client.webhooks import WebhooksClient
+from nextcloud_mcp_server.server.webhook_presets import (
+    WEBHOOK_PRESETS,
+    filter_presets_by_installed_apps,
+    get_preset,
+)
+
+logger = logging.getLogger(__name__)
+
+
+def _get_storage(request: Request):
+    """Get storage instance from app state.
+
+    Args:
+        request: Starlette request object
+
+    Returns:
+        RefreshTokenStorage instance or None
+    """
+    # Try browser_app state first (for /app routes)
+    storage = getattr(request.app.state, "storage", None)
+
+    # Try oauth_context if in OAuth mode
+    if not storage:
+        oauth_ctx = getattr(request.app.state, "oauth_context", None)
+        if oauth_ctx:
+            storage = oauth_ctx.get("storage")
+
+    return storage
+
+
+async def _get_installed_apps(http_client: httpx.AsyncClient) -> list[str]:
+    """Get list of installed and enabled apps from Nextcloud capabilities.
+
+    Args:
+        http_client: Authenticated HTTP client
+
+    Returns:
+        List of installed app names (e.g., ["notes", "calendar", "forms"])
+    """
+    try:
+        response = await http_client.get(
+            "/ocs/v2.php/cloud/capabilities",
+            headers={"OCS-APIRequest": "true", "Accept": "application/json"},
+        )
+        response.raise_for_status()
+        data = response.json()
+
+        # Extract app names from capabilities
+        capabilities = data.get("ocs", {}).get("data", {}).get("capabilities", {})
+        # Filter out core NC capabilities (not apps)
+        core_keys = {"version", "core"}
+        app_keys = set(capabilities.keys()) - core_keys
+        return sorted(app_keys)
+    except Exception as e:
+        logger.warning(f"Failed to get installed apps from capabilities: {e}")
+        return []
+
+
+def _get_webhook_uri() -> str:
+    """Get the webhook endpoint URI for this MCP server.
+
+    This function determines the correct webhook URL based on the environment:
+    1. Uses WEBHOOK_INTERNAL_URL if explicitly set (highest priority)
+    2. Detects Docker environment and uses internal service name
+    3. Falls back to NEXTCLOUD_MCP_SERVER_URL
+
+    In Docker environments, Nextcloud needs to reach the MCP service using
+    the internal Docker network hostname (e.g., http://mcp:8000), not localhost.
+
+    Returns:
+        Full webhook endpoint URL accessible from Nextcloud
+    """
+    # Explicit override (highest priority)
+    webhook_url = os.getenv("WEBHOOK_INTERNAL_URL")
+    if webhook_url:
+        return f"{webhook_url}/webhooks/nextcloud"
+
+    # Detect Docker environment
+    # Check for common Docker indicators
+    is_docker = (
+        os.path.exists("/.dockerenv")  # Docker container marker file
+        or os.path.exists("/run/.containerenv")  # Podman marker
+        or os.getenv("DOCKER_CONTAINER") == "true"  # Explicit flag
+    )
+
+    if is_docker:
+        # In Docker, use internal service name from NEXTCLOUD_MCP_SERVICE_NAME
+        # or default to 'mcp' (docker-compose service name)
+        service_name = os.getenv("NEXTCLOUD_MCP_SERVICE_NAME", "mcp")
+        port = os.getenv("NEXTCLOUD_MCP_PORT", "8000")
+        logger.debug(
+            f"Docker environment detected, using internal URL: http://{service_name}:{port}"
+        )
+        return f"http://{service_name}:{port}/webhooks/nextcloud"
+
+    # Fallback to configured server URL (for non-Docker deployments)
+    server_url = os.getenv("NEXTCLOUD_MCP_SERVER_URL", "http://localhost:8000")
+    return f"{server_url}/webhooks/nextcloud"
+
+
+async def _get_authenticated_client(request: Request) -> httpx.AsyncClient:
+    """Get an authenticated HTTP client for Nextcloud API calls.
+
+    Args:
+        request: Starlette request object
+
+    Returns:
+        Authenticated httpx.AsyncClient
+
+    Raises:
+        RuntimeError: If unable to create authenticated client
+    """
+    # Get OAuth context from app state
+    oauth_ctx = getattr(request.app.state, "oauth_context", None)
+
+    # BasicAuth mode - use credentials from environment
+    if not oauth_ctx:
+        nextcloud_host = os.getenv("NEXTCLOUD_HOST")
+        username = os.getenv("NEXTCLOUD_USERNAME")
+        password = os.getenv("NEXTCLOUD_PASSWORD")
+
+        if not all([nextcloud_host, username, password]):
+            raise RuntimeError("BasicAuth credentials not configured")
+
+        assert nextcloud_host is not None  # Type narrowing for type checker
+        return httpx.AsyncClient(
+            base_url=nextcloud_host,
+            auth=(username, password),
+            timeout=30.0,
+        )
+
+    # OAuth mode - get token from session
+    storage = oauth_ctx.get("storage")
+    session_id = request.cookies.get("mcp_session")
+
+    if not storage or not session_id:
+        raise RuntimeError("Session not found")
+
+    token_data = await storage.get_refresh_token(session_id)
+    if not token_data or "access_token" not in token_data:
+        raise RuntimeError("No access token found in session")
+
+    access_token = token_data["access_token"]
+    nextcloud_host = oauth_ctx.get("config", {}).get("nextcloud_host", "")
+
+    if not nextcloud_host:
+        raise RuntimeError("Nextcloud host not configured")
+
+    return httpx.AsyncClient(
+        base_url=nextcloud_host,
+        headers={"Authorization": f"Bearer {access_token}"},
+        timeout=30.0,
+    )
+
+
+async def _get_enabled_presets(
+    webhooks_client: WebhooksClient,
+    storage=None,
+) -> dict[str, list[int]]:
+    """Get currently enabled webhook presets.
+
+    Reads from database first for better performance. Falls back to API if needed.
+
+    Args:
+        webhooks_client: Webhooks API client
+        storage: Optional RefreshTokenStorage instance
+
+    Returns:
+        Dictionary mapping preset_id to list of webhook IDs
+    """
+    try:
+        # Try database first (faster, works offline)
+        if storage:
+            all_webhooks = await storage.list_all_webhooks()
+            enabled_presets: dict[str, list[int]] = {}
+
+            for webhook in all_webhooks:
+                preset_id = webhook["preset_id"]
+                webhook_id = webhook["webhook_id"]
+
+                if preset_id not in enabled_presets:
+                    enabled_presets[preset_id] = []
+                enabled_presets[preset_id].append(webhook_id)
+
+            return enabled_presets
+
+        # Fallback to API query
+        registered_webhooks = await webhooks_client.list_webhooks()
+        webhook_uri = _get_webhook_uri()
+
+        # Group webhooks by preset based on matching events
+        enabled_presets: dict[str, list[int]] = {}
+
+        for preset_id, preset in WEBHOOK_PRESETS.items():
+            preset_event_classes = {event["event"] for event in preset["events"]}
+            matching_webhooks = []
+
+            for webhook in registered_webhooks:
+                # Check if webhook matches this preset
+                if (
+                    webhook.get("uri") == webhook_uri
+                    and webhook.get("event") in preset_event_classes
+                ):
+                    matching_webhooks.append(webhook["id"])
+
+            if matching_webhooks:
+                enabled_presets[preset_id] = matching_webhooks
+
+        return enabled_presets
+
+    except Exception as e:
+        logger.error(f"Failed to list webhooks: {e}")
+        return {}
+
+
+@requires("authenticated", redirect="oauth_login")
+async def webhook_management_pane(request: Request) -> HTMLResponse:
+    """Webhook management pane - returns HTML for webhook configuration.
+
+    This endpoint checks if the user is an admin and returns either:
+    - Admin view: Webhook management interface with preset controls
+    - Non-admin view: Message indicating admin-only access
+
+    Args:
+        request: Starlette request object
+
+    Returns:
+        HTML response with webhook management interface or access denied message
+    """
+    try:
+        # Get authenticated HTTP client
+        http_client = await _get_authenticated_client(request)
+        username = request.user.display_name
+
+        # Check admin permissions
+        is_admin = await is_nextcloud_admin(request, http_client)
+
+        if not is_admin:
+            return HTMLResponse(
+                content="""
+                <div class="info-message">
+                    <p><strong>Admin Access Required</strong></p>
+                    <p>Webhook management is only available to Nextcloud administrators.</p>
+                    <p>Your account does not have admin privileges.</p>
+                </div>
+                """
+            )
+
+        # Get webhooks client
+        webhooks_client = WebhooksClient(http_client, username)
+
+        # Get storage for database-backed webhook tracking
+        storage = _get_storage(request)
+
+        # Get installed apps to filter presets
+        installed_apps = await _get_installed_apps(http_client)
+        logger.debug(f"Installed apps: {installed_apps}")
+
+        # Get currently enabled presets (from database or API)
+        enabled_presets = await _get_enabled_presets(webhooks_client, storage)
+
+        # Filter presets based on installed apps
+        available_presets = filter_presets_by_installed_apps(installed_apps)
+
+        # Build preset cards HTML
+        preset_cards_html = ""
+        for preset_id, preset in available_presets:
+            is_enabled = preset_id in enabled_presets
+            num_webhooks = len(enabled_presets.get(preset_id, []))
+
+            # Status badge
+            if is_enabled:
+                status_badge = f'<span style="color: #4caf50; font-weight: bold;">✓ Enabled ({num_webhooks} webhooks)</span>'
+                action_button = f"""
+                <button
+                    hx-delete="/app/webhooks/disable/{preset_id}"
+                    hx-target="#preset-{preset_id}"
+                    hx-swap="outerHTML"
+                    class="button"
+                    style="background-color: #ff9800;">
+                    Disable
+                </button>
+                """
+            else:
+                status_badge = '<span style="color: #999;">Not Enabled</span>'
+                action_button = f"""
+                <button
+                    hx-post="/app/webhooks/enable/{preset_id}"
+                    hx-target="#preset-{preset_id}"
+                    hx-swap="outerHTML"
+                    class="button button-primary">
+                    Enable
+                </button>
+                """
+
+            preset_cards_html += f"""
+            <div id="preset-{preset_id}" style="border: 1px solid #e0e0e0; border-radius: 6px; padding: 20px; margin: 15px 0;">
+                <h3 style="margin-top: 0; color: #0082c9;">{preset["name"]}</h3>
+                <p style="color: #666; margin: 10px 0;">{preset["description"]}</p>
+                <p style="font-size: 13px; color: #999;">
+                    <strong>App:</strong> {preset["app"]} |
+                    <strong>Events:</strong> {len(preset["events"])}
+                </p>
+                <div style="margin-top: 15px; display: flex; align-items: center; gap: 15px;">
+                    <div>{status_badge}</div>
+                    <div>{action_button}</div>
+                </div>
+            </div>
+            """
+
+        # Get webhook endpoint URL for display
+        webhook_uri = _get_webhook_uri()
+
+        html_content = f"""
+        <h2>Webhook Management</h2>
+        <div class="info-message">
+            <p><strong>About Webhooks</strong></p>
+            <p>Webhooks enable real-time synchronization by notifying this server when content changes in Nextcloud.</p>
+            <p><strong>Endpoint:</strong> <code>{webhook_uri}</code></p>
+        </div>
+
+        <h3 style="margin-top: 30px;">Available Presets</h3>
+        <p style="color: #666;">Enable webhook presets with one click for common synchronization scenarios.</p>
+        <p style="color: #999; font-size: 13px; margin-top: 5px;">Showing {len(available_presets)} preset(s) for your installed apps ({len(installed_apps)} detected)</p>
+
+        {preset_cards_html}
+        """
+
+        return HTMLResponse(content=html_content)
+
+    except Exception as e:
+        logger.error(f"Error loading webhook management pane: {e}", exc_info=True)
+        return HTMLResponse(
+            content=f"""
+            <div class="warning">
+                <p><strong>Error Loading Webhooks</strong></p>
+                <p>{str(e)}</p>
+            </div>
+            """,
+            status_code=500,
+        )
+
+
+@requires("authenticated", redirect="oauth_login")
+async def enable_webhook_preset(request: Request) -> HTMLResponse:
+    """Enable a webhook preset by registering all webhooks.
+
+    Args:
+        request: Starlette request object (preset_id in path)
+
+    Returns:
+        HTML response with updated preset card
+    """
+    preset_id = request.path_params["preset_id"]
+
+    try:
+        # Get authenticated HTTP client
+        http_client = await _get_authenticated_client(request)
+        username = request.user.display_name
+
+        # Check admin permissions
+        is_admin = await is_nextcloud_admin(request, http_client)
+        if not is_admin:
+            return HTMLResponse(
+                content='<div class="warning">Admin access required</div>',
+                status_code=403,
+            )
+
+        # Get preset configuration
+        preset = get_preset(preset_id)
+        if not preset:
+            return HTMLResponse(
+                content=f'<div class="warning">Unknown preset: {preset_id}</div>',
+                status_code=404,
+            )
+
+        # Register webhooks
+        webhooks_client = WebhooksClient(http_client, username)
+        webhook_uri = _get_webhook_uri()
+        registered_ids = []
+
+        for event_config in preset["events"]:
+            webhook_data = await webhooks_client.create_webhook(
+                event=event_config["event"],
+                uri=webhook_uri,
+                event_filter=event_config["filter"] if event_config["filter"] else None,
+            )
+            webhook_id = webhook_data["id"]
+            registered_ids.append(webhook_id)
+            logger.info(f"Registered webhook {webhook_id} for {event_config['event']}")
+
+        # Persist webhook IDs to database
+        storage = _get_storage(request)
+        if storage:
+            for webhook_id in registered_ids:
+                await storage.store_webhook(webhook_id, preset_id)
+            logger.info(
+                f"Persisted {len(registered_ids)} webhook(s) for preset '{preset_id}' to database"
+            )
+
+        # Return updated card
+        num_webhooks = len(registered_ids)
+        return HTMLResponse(
+            content=f"""
+            <div id="preset-{preset_id}" style="border: 1px solid #e0e0e0; border-radius: 6px; padding: 20px; margin: 15px 0;">
+                <h3 style="margin-top: 0; color: #0082c9;">{preset["name"]}</h3>
+                <p style="color: #666; margin: 10px 0;">{preset["description"]}</p>
+                <p style="font-size: 13px; color: #999;">
+                    <strong>App:</strong> {preset["app"]} |
+                    <strong>Events:</strong> {len(preset["events"])}
+                </p>
+                <div style="margin-top: 15px; display: flex; align-items: center; gap: 15px;">
+                    <div><span style="color: #4caf50; font-weight: bold;">✓ Enabled ({num_webhooks} webhooks)</span></div>
+                    <div>
+                        <button
+                            hx-delete="/app/webhooks/disable/{preset_id}"
+                            hx-target="#preset-{preset_id}"
+                            hx-swap="outerHTML"
+                            class="button"
+                            style="background-color: #ff9800;">
+                            Disable
+                        </button>
+                    </div>
+                </div>
+            </div>
+            """
+        )
+
+    except Exception as e:
+        logger.error(f"Failed to enable preset {preset_id}: {e}", exc_info=True)
+        return HTMLResponse(
+            content=f'<div class="warning">Failed to enable preset: {str(e)}</div>',
+            status_code=500,
+        )
+
+
+@requires("authenticated", redirect="oauth_login")
+async def disable_webhook_preset(request: Request) -> HTMLResponse:
+    """Disable a webhook preset by deleting all registered webhooks.
+
+    Args:
+        request: Starlette request object (preset_id in path)
+
+    Returns:
+        HTML response with updated preset card
+    """
+    preset_id = request.path_params["preset_id"]
+
+    try:
+        # Get authenticated HTTP client
+        http_client = await _get_authenticated_client(request)
+        username = request.user.display_name
+
+        # Check admin permissions
+        is_admin = await is_nextcloud_admin(request, http_client)
+        if not is_admin:
+            return HTMLResponse(
+                content='<div class="warning">Admin access required</div>',
+                status_code=403,
+            )
+
+        # Get preset configuration
+        preset = get_preset(preset_id)
+        if not preset:
+            return HTMLResponse(
+                content=f'<div class="warning">Unknown preset: {preset_id}</div>',
+                status_code=404,
+            )
+
+        # Find and delete matching webhooks
+        webhooks_client = WebhooksClient(http_client, username)
+
+        # Get webhook IDs from database first (more reliable)
+        storage = _get_storage(request)
+        if storage:
+            webhook_ids = await storage.get_webhooks_by_preset(preset_id)
+        else:
+            # Fallback to API query if storage not available
+            enabled_presets = await _get_enabled_presets(webhooks_client)
+            webhook_ids = enabled_presets.get(preset_id, [])
+
+        for webhook_id in webhook_ids:
+            await webhooks_client.delete_webhook(webhook_id)
+            logger.info(f"Deleted webhook {webhook_id} from preset {preset_id}")
+
+        # Remove from database
+        if storage:
+            deleted_count = await storage.clear_preset_webhooks(preset_id)
+            logger.info(
+                f"Removed {deleted_count} webhook(s) for preset '{preset_id}' from database"
+            )
+
+        # Return updated card
+        return HTMLResponse(
+            content=f"""
+            <div id="preset-{preset_id}" style="border: 1px solid #e0e0e0; border-radius: 6px; padding: 20px; margin: 15px 0;">
+                <h3 style="margin-top: 0; color: #0082c9;">{preset["name"]}</h3>
+                <p style="color: #666; margin: 10px 0;">{preset["description"]}</p>
+                <p style="font-size: 13px; color: #999;">
+                    <strong>App:</strong> {preset["app"]} |
+                    <strong>Events:</strong> {len(preset["events"])}
+                </p>
+                <div style="margin-top: 15px; display: flex; align-items: center; gap: 15px;">
+                    <div><span style="color: #999;">Not Enabled</span></div>
+                    <div>
+                        <button
+                            hx-post="/app/webhooks/enable/{preset_id}"
+                            hx-target="#preset-{preset_id}"
+                            hx-swap="outerHTML"
+                            class="button button-primary">
+                            Enable
+                        </button>
+                    </div>
+                </div>
+            </div>
+            """
+        )
+
+    except Exception as e:
+        logger.error(f"Failed to disable preset {preset_id}: {e}", exc_info=True)
+        return HTMLResponse(
+            content=f'<div class="warning">Failed to disable preset: {str(e)}</div>',
+            status_code=500,
+        )

nextcloud_mcp_server/cli.py

@@ -0,0 +1,257 @@
+import os
+
+import click
+import uvicorn
+
+from nextcloud_mcp_server.config import (
+    get_settings,
+)
+from nextcloud_mcp_server.observability import get_uvicorn_logging_config
+
+from .app import get_app
+
+
+@click.command()
+@click.option(
+    "--host", "-h", default="127.0.0.1", show_default=True, help="Server host"
+)
+@click.option(
+    "--port", "-p", type=int, default=8000, show_default=True, help="Server port"
+)
+@click.option(
+    "--log-level",
+    "-l",
+    default="info",
+    show_default=True,
+    type=click.Choice(["critical", "error", "warning", "info", "debug", "trace"]),
+    help="Logging level",
+)
+@click.option(
+    "--transport",
+    "-t",
+    default="sse",
+    show_default=True,
+    type=click.Choice(["sse", "streamable-http", "http"]),
+    help="MCP transport protocol",
+)
+@click.option(
+    "--enable-app",
+    "-e",
+    multiple=True,
+    type=click.Choice(
+        ["notes", "tables", "webdav", "calendar", "contacts", "cookbook", "deck"]
+    ),
+    help="Enable specific Nextcloud app APIs. Can be specified multiple times. If not specified, all apps are enabled.",
+)
+@click.option(
+    "--oauth/--no-oauth",
+    default=None,
+    help="Force OAuth mode (if enabled) or BasicAuth mode (if disabled). By default, auto-detected based on environment variables.",
+)
+@click.option(
+    "--oauth-client-id",
+    envvar="NEXTCLOUD_OIDC_CLIENT_ID",
+    help="OAuth client ID (can also use NEXTCLOUD_OIDC_CLIENT_ID env var)",
+)
+@click.option(
+    "--oauth-client-secret",
+    envvar="NEXTCLOUD_OIDC_CLIENT_SECRET",
+    help="OAuth client secret (can also use NEXTCLOUD_OIDC_CLIENT_SECRET env var)",
+)
+@click.option(
+    "--mcp-server-url",
+    envvar="NEXTCLOUD_MCP_SERVER_URL",
+    default="http://localhost:8000",
+    show_default=True,
+    help="MCP server URL for OAuth callbacks (can also use NEXTCLOUD_MCP_SERVER_URL env var)",
+)
+@click.option(
+    "--nextcloud-host",
+    envvar="NEXTCLOUD_HOST",
+    help="Nextcloud instance URL (can also use NEXTCLOUD_HOST env var)",
+)
+@click.option(
+    "--nextcloud-username",
+    envvar="NEXTCLOUD_USERNAME",
+    help="Nextcloud username for BasicAuth (can also use NEXTCLOUD_USERNAME env var)",
+)
+@click.option(
+    "--nextcloud-password",
+    envvar="NEXTCLOUD_PASSWORD",
+    help="Nextcloud password for BasicAuth (can also use NEXTCLOUD_PASSWORD env var)",
+)
+@click.option(
+    "--oauth-scopes",
+    envvar="NEXTCLOUD_OIDC_SCOPES",
+    default="openid profile email notes:read notes:write calendar:read calendar:write todo:read todo:write contacts:read contacts:write cookbook:read cookbook:write deck:read deck:write tables:read tables:write files:read files:write sharing:read sharing:write",
+    show_default=True,
+    help="OAuth scopes to request during client registration. These define the maximum allowed scopes for the client. Note: Actual supported scopes are discovered dynamically from MCP tools at runtime. (can also use NEXTCLOUD_OIDC_SCOPES env var)",
+)
+@click.option(
+    "--oauth-token-type",
+    envvar="NEXTCLOUD_OIDC_TOKEN_TYPE",
+    default="bearer",
+    show_default=True,
+    type=click.Choice(["bearer", "jwt"], case_sensitive=False),
+    help="OAuth token type (can also use NEXTCLOUD_OIDC_TOKEN_TYPE env var)",
+)
+@click.option(
+    "--public-issuer-url",
+    envvar="NEXTCLOUD_PUBLIC_ISSUER_URL",
+    help="Public issuer URL for OAuth (can also use NEXTCLOUD_PUBLIC_ISSUER_URL env var)",
+)
+def run(
+    host: str,
+    port: int,
+    log_level: str,
+    transport: str,
+    enable_app: tuple[str, ...],
+    oauth: bool | None,
+    oauth_client_id: str | None,
+    oauth_client_secret: str | None,
+    mcp_server_url: str,
+    nextcloud_host: str | None,
+    nextcloud_username: str | None,
+    nextcloud_password: str | None,
+    oauth_scopes: str,
+    oauth_token_type: str,
+    public_issuer_url: str | None,
+):
+    """
+    Run the Nextcloud MCP server.
+
+    \b
+    Authentication Modes:
+      - BasicAuth: Set NEXTCLOUD_USERNAME and NEXTCLOUD_PASSWORD
+      - OAuth: Leave USERNAME/PASSWORD unset (requires OIDC app enabled)
+
+    \b
+    Examples:
+      # BasicAuth mode with CLI options
+      $ nextcloud-mcp-server --nextcloud-host=https://cloud.example.com \\
+          --nextcloud-username=admin --nextcloud-password=secret
+
+      # BasicAuth mode with env vars (recommended for credentials)
+      $ export NEXTCLOUD_HOST=https://cloud.example.com
+      $ export NEXTCLOUD_USERNAME=admin
+      $ export NEXTCLOUD_PASSWORD=secret
+      $ nextcloud-mcp-server --host 0.0.0.0 --port 8000
+
+      # OAuth mode with auto-registration
+      $ nextcloud-mcp-server --nextcloud-host=https://cloud.example.com --oauth
+
+      # OAuth mode with pre-configured client
+      $ nextcloud-mcp-server --nextcloud-host=https://cloud.example.com --oauth \\
+          --oauth-client-id=xxx --oauth-client-secret=yyy
+
+      # OAuth mode with custom scopes and JWT tokens
+      $ nextcloud-mcp-server --nextcloud-host=https://cloud.example.com --oauth \\
+          --oauth-scopes="openid notes:read notes:write" --oauth-token-type=jwt
+
+      # OAuth with public issuer URL (for Docker/proxy setups)
+      $ nextcloud-mcp-server --nextcloud-host=http://app --oauth \\
+          --public-issuer-url=http://localhost:8080
+    """
+    # Set env vars from CLI options if provided
+    if nextcloud_host:
+        os.environ["NEXTCLOUD_HOST"] = nextcloud_host
+    if nextcloud_username:
+        os.environ["NEXTCLOUD_USERNAME"] = nextcloud_username
+    if nextcloud_password:
+        os.environ["NEXTCLOUD_PASSWORD"] = nextcloud_password
+    if oauth_client_id:
+        os.environ["NEXTCLOUD_OIDC_CLIENT_ID"] = oauth_client_id
+    if oauth_client_secret:
+        os.environ["NEXTCLOUD_OIDC_CLIENT_SECRET"] = oauth_client_secret
+    if oauth_scopes:
+        os.environ["NEXTCLOUD_OIDC_SCOPES"] = oauth_scopes
+    if oauth_token_type:
+        os.environ["NEXTCLOUD_OIDC_TOKEN_TYPE"] = oauth_token_type
+    if mcp_server_url:
+        os.environ["NEXTCLOUD_MCP_SERVER_URL"] = mcp_server_url
+    if public_issuer_url:
+        os.environ["NEXTCLOUD_PUBLIC_ISSUER_URL"] = public_issuer_url
+
+    # Force OAuth mode if explicitly requested
+    if oauth is True:
+        # Clear username/password to force OAuth mode
+        if "NEXTCLOUD_USERNAME" in os.environ:
+            click.echo(
+                "Warning: --oauth flag set, ignoring NEXTCLOUD_USERNAME", err=True
+            )
+            del os.environ["NEXTCLOUD_USERNAME"]
+        if "NEXTCLOUD_PASSWORD" in os.environ:
+            click.echo(
+                "Warning: --oauth flag set, ignoring NEXTCLOUD_PASSWORD", err=True
+            )
+            del os.environ["NEXTCLOUD_PASSWORD"]
+
+        # Validate OAuth configuration
+        nextcloud_host = os.getenv("NEXTCLOUD_HOST")
+        if not nextcloud_host:
+            raise click.ClickException(
+                "OAuth mode requires NEXTCLOUD_HOST environment variable to be set"
+            )
+
+        # Check if we have client credentials OR if dynamic registration is possible
+        has_client_creds = os.getenv("NEXTCLOUD_OIDC_CLIENT_ID") and os.getenv(
+            "NEXTCLOUD_OIDC_CLIENT_SECRET"
+        )
+
+        if not has_client_creds:
+            # No client credentials - will attempt dynamic registration
+            # Show helpful message before server starts
+            click.echo("", err=True)
+            click.echo("OAuth Configuration:", err=True)
+            click.echo("  Mode: Dynamic Client Registration", err=True)
+            click.echo("  Host: " + nextcloud_host, err=True)
+            click.echo("  Storage: SQLite (TOKEN_STORAGE_DB)", err=True)
+            click.echo("", err=True)
+            click.echo(
+                "Note: Make sure 'Dynamic Client Registration' is enabled", err=True
+            )
+            click.echo("      in your Nextcloud OIDC app settings.", err=True)
+            click.echo("", err=True)
+        else:
+            click.echo("", err=True)
+            click.echo("OAuth Configuration:", err=True)
+            click.echo("  Mode: Pre-configured Client", err=True)
+            click.echo("  Host: " + nextcloud_host, err=True)
+            click.echo(
+                "  Client ID: "
+                + os.getenv("NEXTCLOUD_OIDC_CLIENT_ID", "")[:16]
+                + "...",
+                err=True,
+            )
+            click.echo("", err=True)
+
+    elif oauth is False:
+        # Force BasicAuth mode - verify credentials exist
+        if not os.getenv("NEXTCLOUD_USERNAME") or not os.getenv("NEXTCLOUD_PASSWORD"):
+            raise click.ClickException(
+                "--no-oauth flag set but NEXTCLOUD_USERNAME or NEXTCLOUD_PASSWORD not set"
+            )
+
+    enabled_apps = list(enable_app) if enable_app else None
+
+    app = get_app(transport=transport, enabled_apps=enabled_apps)
+
+    # Get observability settings and create uvicorn logging config
+    settings = get_settings()
+    uvicorn_log_config = get_uvicorn_logging_config(
+        log_format=settings.log_format,
+        log_level=settings.log_level,
+        include_trace_context=settings.log_include_trace_context,
+    )
+
+    uvicorn.run(
+        app=app,
+        host=host,
+        port=port,
+        log_level=log_level,
+        log_config=uvicorn_log_config,
+    )
+
+
+if __name__ == "__main__":
+    run()

nextcloud_mcp_server/client/__init__.py

@@ -9,6 +9,7 @@ from httpx import (
     BasicAuth,
     Request,
     Response,
+    Timeout,
 )
 
 from ..controllers.notes_search import NotesSearchController
@@ -22,6 +23,7 @@ from .sharing import SharingClient
 from .tables import TablesClient
 from .users import UsersClient
 from .webdav import WebDAVClient
+from .webhooks import WebhooksClient
 
 logger = logging.getLogger(__name__)
 
@@ -66,6 +68,7 @@ class NextcloudClient:
             auth=auth,
             transport=AsyncDisableCookieTransport(AsyncHTTPTransport()),
             event_hooks={"request": [log_request], "response": [log_response]},
+            timeout=Timeout(timeout=30, connect=5),
         )
 
         # Initialize app clients
@@ -81,6 +84,7 @@ class NextcloudClient:
         self.users = UsersClient(self._client, username)
         self.groups = GroupsClient(self._client, username)
         self.sharing = SharingClient(self._client, username)
+        self.webhooks = WebhooksClient(self._client, username)
 
         # Initialize controllers
         self._notes_search = NotesSearchController()

nextcloud_mcp_server/client/base.py

@@ -5,8 +5,15 @@ import time
 from abc import ABC
 from functools import wraps
 
+import anyio
 from httpx import AsyncClient, HTTPStatusError, RequestError, codes
 
+from nextcloud_mcp_server.observability.metrics import (
+    record_nextcloud_api_call,
+    record_nextcloud_api_retry,
+)
+from nextcloud_mcp_server.observability.tracing import trace_nextcloud_api_call
+
 logger = logging.getLogger(__name__)
 
 
@@ -38,7 +45,10 @@ def retry_on_429(func):
                     logger.warning(
                         f"429 Client Error: Too Many Requests, Number of attempts: {retries}"
                     )
-                    time.sleep(5)
+                    # Record retry metric (extract app name from args if available)
+                    if len(args) > 0 and hasattr(args[0], "app_name"):
+                        record_nextcloud_api_retry(app=args[0].app_name, reason="429")
+                    await anyio.sleep(5)
                 elif e.response.status_code == 404:
                     # 404 errors are often expected (e.g., checking if attachments exist)
                     # Log as debug instead of warning
@@ -72,6 +82,9 @@ def retry_on_429(func):
 class BaseNextcloudClient(ABC):
     """Base class for all Nextcloud app clients."""
 
+    # Subclasses should set this to identify the app for metrics/tracing
+    app_name: str = "unknown"
+
     def __init__(self, http_client: AsyncClient, username: str):
         """Initialize with shared HTTP client and username.
 
@@ -88,7 +101,7 @@ class BaseNextcloudClient(ABC):
 
     @retry_on_429
     async def _make_request(self, method: str, url: str, **kwargs):
-        """Common request wrapper with logging and error handling.
+        """Common request wrapper with logging, tracing, and error handling.
 
         Args:
             method: HTTP method
@@ -99,6 +112,47 @@ class BaseNextcloudClient(ABC):
             Response object
         """
         logger.debug(f"Making {method} request to {url}")
-        response = await self._client.request(method, url, **kwargs)
-        response.raise_for_status()
-        return response
+
+        # Start timer for metrics
+        start_time = time.time()
+        status_code = 0
+
+        try:
+            # Wrap request in trace span
+            with trace_nextcloud_api_call(
+                app=self.app_name,
+                method=method,
+                path=url,
+            ):
+                response = await self._client.request(method, url, **kwargs)
+                status_code = response.status_code
+                response.raise_for_status()
+
+                # Record successful API call metrics
+                duration = time.time() - start_time
+                record_nextcloud_api_call(
+                    app=self.app_name,
+                    method=method,
+                    status_code=status_code,
+                    duration=duration,
+                )
+
+                return response
+
+        except (HTTPStatusError, RequestError) as e:
+            # Record error metrics
+            if isinstance(e, HTTPStatusError):
+                status_code = e.response.status_code
+            else:
+                status_code = 0  # Connection error, no status code
+
+            duration = time.time() - start_time
+            record_nextcloud_api_call(
+                app=self.app_name,
+                method=method,
+                status_code=status_code,
+                duration=duration,
+            )
+
+            # Re-raise the exception
+            raise

nextcloud_mcp_server/client/contacts.py

@@ -13,6 +13,8 @@ logger = logging.getLogger(__name__)
 class ContactsClient(BaseNextcloudClient):
     """Client for NextCloud CardDAV contact operations."""
 
+    app_name = "contacts"
+
     def _get_carddav_base_path(self) -> str:
         """Helper to get the base CardDAV path for contacts."""
         return f"/remote.php/dav/addressbooks/users/{self.username}"

nextcloud_mcp_server/client/cookbook.py

@@ -13,6 +13,8 @@ logger = logging.getLogger(__name__)
 class CookbookClient(BaseNextcloudClient):
     """Client for Nextcloud Cookbook app operations."""
 
+    app_name = "cookbook"
+
     async def get_version(self) -> Dict[str, Any]:
         """Get Cookbook app and API version."""
         response = await self._make_request("GET", "/apps/cookbook/api/version")

nextcloud_mcp_server/client/deck.py

@@ -17,6 +17,8 @@ from nextcloud_mcp_server.models.deck import (
 class DeckClient(BaseNextcloudClient):
     """Client for Nextcloud Deck app operations."""
 
+    app_name = "deck"
+
     def _get_deck_headers(
         self, additional_headers: Optional[Dict[str, str]] = None
     ) -> Dict[str, str]:

nextcloud_mcp_server/client/groups.py

@@ -11,6 +11,8 @@ logger = logging.getLogger(__name__)
 class GroupsClient(BaseNextcloudClient):
     """Client for Nextcloud Groups API operations."""
 
+    app_name = "groups"
+
     @retry_on_429
     async def search_groups(
         self,

nextcloud_mcp_server/client/notes.py

@@ -11,23 +11,64 @@ logger = logging.getLogger(__name__)
 class NotesClient(BaseNextcloudClient):
     """Client for Nextcloud Notes app operations."""
 
+    app_name = "notes"
+
     async def get_settings(self) -> Dict[str, Any]:
         """Get Notes app settings."""
         response = await self._make_request("GET", "/apps/notes/api/v1/settings")
         return response.json()
 
-    async def get_all_notes(self) -> AsyncIterator[Dict[str, Any]]:
-        """Get all notes, yielding them one at a time."""
+    async def get_all_notes(
+        self, prune_before: Optional[int] = None
+    ) -> AsyncIterator[Dict[str, Any]]:
+        """Get all notes, yielding them one at a time.
+
+        The Notes API returns changed notes with full data in chunks, and ALL note IDs
+        (with only 'id' field) in the last chunk for deletion detection. This causes
+        duplicates which we handle by tracking seen IDs (first occurrence with full
+        data is kept, later pruned duplicates are skipped).
+
+        Args:
+            prune_before: Optional Unix timestamp. Notes unchanged since this time
+                         are pruned (only 'id' field returned in last chunk).
+                         Reduces data transfer for large note collections.
+
+        Yields:
+            Note dictionaries with full data (deduplicated).
+        """
         cursor = ""
+        seen_ids: set[int] = set()
 
         while True:
+            params: Dict[str, Any] = {"chunkSize": 100}
+            if cursor:
+                params["chunkCursor"] = cursor
+            if prune_before is not None:
+                params["pruneBefore"] = prune_before
+
             response = await self._make_request(
                 "GET",
                 "/apps/notes/api/v1/notes",
-                params={"chunkSize": 10, "chunkCursor": cursor},
+                params=params,
             )
-            for note in response.json():
+            response_data = response.json()
+
+            for note in response_data:
+                note_id = note.get("id")
+                if note_id is None:
+                    logger.warning(f"Skipping note without ID: {note}")
+                    continue
+
+                # Skip duplicates (API returns all IDs in last chunk for deletion detection)
+                if note_id in seen_ids:
+                    logger.debug(
+                        f"Skipping duplicate note {note_id} (pruned version in last chunk)"
+                    )
+                    continue
+
+                seen_ids.add(note_id)
                 yield note
+
             if "X-Notes-Chunk-Cursor" not in response.headers:
                 break
             cursor = response.headers["X-Notes-Chunk-Cursor"]

nextcloud_mcp_server/client/sharing.py

@@ -11,6 +11,8 @@ logger = logging.getLogger(__name__)
 class SharingClient(BaseNextcloudClient):
     """Client for Nextcloud OCS Sharing API operations."""
 
+    app_name = "sharing"
+
     @retry_on_429
     async def create_share(
         self,

nextcloud_mcp_server/client/tables.py

@@ -11,6 +11,8 @@ logger = logging.getLogger(__name__)
 class TablesClient(BaseNextcloudClient):
     """Client for Nextcloud Tables app operations."""
 
+    app_name = "tables"
+
     async def list_tables(self) -> List[Dict[str, Any]]:
         """List all tables available to the user."""
         response = await self._make_request(

nextcloud_mcp_server/client/users.py

@@ -7,6 +7,8 @@ from nextcloud_mcp_server.models.users import UserDetails
 class UsersClient(BaseNextcloudClient):
     """Client for Nextcloud User API operations."""
 
+    app_name = "users"
+
     def _get_user_headers(
         self, additional_headers: Optional[Dict[str, str]] = None
     ) -> Dict[str, str]:

nextcloud_mcp_server/client/webdav.py

@@ -15,6 +15,8 @@ logger = logging.getLogger(__name__)
 class WebDAVClient(BaseNextcloudClient):
     """Client for Nextcloud WebDAV operations."""
 
+    app_name = "webdav"
+
     async def delete_resource(self, path: str) -> Dict[str, Any]:
         """Delete a resource (file or directory) via WebDAV DELETE."""
         # Ensure path ends with a slash if it's a directory

nextcloud_mcp_server/client/webhooks.py

@@ -0,0 +1,109 @@
+"""Client for Nextcloud Webhook Listeners API operations."""
+
+from typing import Any, Dict, List, Optional
+
+from nextcloud_mcp_server.client.base import BaseNextcloudClient
+
+
+class WebhooksClient(BaseNextcloudClient):
+    """Client for Nextcloud webhook_listeners app API operations."""
+
+    app_name = "webhooks"
+
+    def _get_webhook_headers(
+        self, additional_headers: Optional[Dict[str, str]] = None
+    ) -> Dict[str, str]:
+        """Get standard headers required for Webhook Listeners API calls."""
+        headers = {"OCS-APIRequest": "true", "Accept": "application/json"}
+        if additional_headers:
+            headers.update(additional_headers)
+        return headers
+
+    async def list_webhooks(self) -> List[Dict[str, Any]]:
+        """List all registered webhooks for the current user.
+
+        Returns:
+            List of webhook registrations with id, uri, event, filters, etc.
+        """
+        headers = self._get_webhook_headers()
+        response = await self._make_request(
+            "GET",
+            "/ocs/v2.php/apps/webhook_listeners/api/v1/webhooks",
+            headers=headers,
+        )
+        data = response.json()["ocs"]["data"]
+        return data if isinstance(data, list) else []
+
+    async def create_webhook(
+        self,
+        event: str,
+        uri: str,
+        http_method: str = "POST",
+        auth_method: str = "none",
+        headers: Optional[Dict[str, str]] = None,
+        event_filter: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        """Register a new webhook for the specified event.
+
+        Args:
+            event: Fully qualified event class name (e.g., "OCP\\Files\\Events\\Node\\NodeCreatedEvent")
+            uri: Webhook endpoint URL to receive event notifications
+            http_method: HTTP method for webhook delivery (default: "POST")
+            auth_method: Authentication method ("none", "bearer", etc.)
+            headers: Custom headers to include in webhook requests (e.g., Authorization header)
+            event_filter: JSON object specifying event filters (e.g., {"user.uid": "bob"})
+
+        Returns:
+            Webhook registration details including webhook ID
+        """
+        data: Dict[str, Any] = {
+            "httpMethod": http_method,
+            "uri": uri,
+            "event": event,
+            "authMethod": auth_method,
+        }
+
+        if headers:
+            data["headers"] = headers
+
+        if event_filter:
+            data["eventFilter"] = event_filter
+
+        request_headers = self._get_webhook_headers()
+        response = await self._make_request(
+            "POST",
+            "/ocs/v2.php/apps/webhook_listeners/api/v1/webhooks",
+            json=data,
+            headers=request_headers,
+        )
+        return response.json()["ocs"]["data"]
+
+    async def delete_webhook(self, webhook_id: int) -> None:
+        """Delete a webhook registration.
+
+        Args:
+            webhook_id: ID of the webhook to delete
+        """
+        headers = self._get_webhook_headers()
+        await self._make_request(
+            "DELETE",
+            f"/ocs/v2.php/apps/webhook_listeners/api/v1/webhooks/{webhook_id}",
+            headers=headers,
+        )
+
+    async def get_webhook(self, webhook_id: int) -> Dict[str, Any]:
+        """Get details of a specific webhook registration.
+
+        Args:
+            webhook_id: ID of the webhook to retrieve
+
+        Returns:
+            Webhook registration details
+        """
+        headers = self._get_webhook_headers()
+        response = await self._make_request(
+            "GET",
+            f"/ocs/v2.php/apps/webhook_listeners/api/v1/webhooks/{webhook_id}",
+            headers=headers,
+        )
+        return response.json()["ocs"]["data"]

nextcloud_mcp_server/config.py

@@ -1,3 +1,4 @@
+import logging
 import logging.config
 import os
 from dataclasses import dataclass
@@ -152,10 +153,131 @@ class Settings:
     # Token exchange cache settings
     token_exchange_cache_ttl: int = 300  # seconds (5 minutes default)
 
-    # Token settings
+    # Token and webhook storage settings
+    # TOKEN_ENCRYPTION_KEY: Optional - Only required for OAuth token storage operations.
+    #                       Webhook tracking works without encryption key.
+    #                       If set, must be a valid base64-encoded Fernet key (32 bytes).
+    # TOKEN_STORAGE_DB: Path to SQLite database for persistent storage.
+    #                   Used for webhook tracking (all modes) and OAuth token storage.
+    #                   Defaults to /tmp/tokens.db
     token_encryption_key: Optional[str] = None
     token_storage_db: Optional[str] = None
 
+    # Vector sync settings (ADR-007)
+    vector_sync_enabled: bool = False
+    vector_sync_scan_interval: int = 300  # seconds (5 minutes)
+    vector_sync_processor_workers: int = 3
+    vector_sync_queue_max_size: int = 10000
+
+    # Qdrant settings (mutually exclusive modes)
+    qdrant_url: Optional[str] = None  # Network mode: http://qdrant:6333
+    qdrant_location: Optional[str] = None  # Local mode: :memory: or /path/to/data
+    qdrant_api_key: Optional[str] = None
+    qdrant_collection: str = "nextcloud_content"
+
+    # Ollama settings (for embeddings)
+    ollama_base_url: Optional[str] = None
+    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
+    otel_exporter_otlp_endpoint: Optional[str] = None
+    otel_exporter_verify_ssl: bool = False
+    otel_service_name: str = "nextcloud-mcp-server"
+    otel_traces_sampler: str = "always_on"
+    otel_traces_sampler_arg: float = 1.0
+    log_format: str = "text"  # "json" or "text"
+    log_level: str = "INFO"
+    log_include_trace_context: bool = True
+
+    def __post_init__(self):
+        """Validate Qdrant configuration and set defaults."""
+        logger = logging.getLogger(__name__)
+
+        # Ensure mutual exclusivity
+        if self.qdrant_url and self.qdrant_location:
+            raise ValueError(
+                "Cannot set both QDRANT_URL and QDRANT_LOCATION. "
+                "Use QDRANT_URL for network mode or QDRANT_LOCATION for local mode."
+            )
+
+        # Default to :memory: if neither set
+        if not self.qdrant_url and not self.qdrant_location:
+            self.qdrant_location = ":memory:"
+            logger.debug("Using default Qdrant mode: in-memory (:memory:)")
+
+        # Warn if API key set in local mode
+        if self.qdrant_location and self.qdrant_api_key:
+            logger.warning(
+                "QDRANT_API_KEY is set but QDRANT_LOCATION is used (local mode). "
+                "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.
@@ -166,8 +288,8 @@ def get_settings() -> Settings:
     return Settings(
         # OAuth/OIDC settings
         oidc_discovery_url=os.getenv("OIDC_DISCOVERY_URL"),
-        oidc_client_id=os.getenv("OIDC_CLIENT_ID"),
-        oidc_client_secret=os.getenv("OIDC_CLIENT_SECRET"),
+        oidc_client_id=os.getenv("NEXTCLOUD_OIDC_CLIENT_ID"),
+        oidc_client_secret=os.getenv("NEXTCLOUD_OIDC_CLIENT_SECRET"),
         oidc_issuer=os.getenv("OIDC_ISSUER"),
         # Nextcloud settings
         nextcloud_host=os.getenv("NEXTCLOUD_HOST"),
@@ -189,7 +311,43 @@ def get_settings() -> Settings:
         ),
         # Token exchange cache settings
         token_exchange_cache_ttl=int(os.getenv("TOKEN_EXCHANGE_CACHE_TTL", "300")),
-        # Token settings
+        # Token and webhook storage settings (encryption key optional for webhook-only usage)
         token_encryption_key=os.getenv("TOKEN_ENCRYPTION_KEY"),
         token_storage_db=os.getenv("TOKEN_STORAGE_DB", "/tmp/tokens.db"),
+        # Vector sync settings (ADR-007)
+        vector_sync_enabled=(
+            os.getenv("VECTOR_SYNC_ENABLED", "false").lower() == "true"
+        ),
+        vector_sync_scan_interval=int(os.getenv("VECTOR_SYNC_SCAN_INTERVAL", "300")),
+        vector_sync_processor_workers=int(
+            os.getenv("VECTOR_SYNC_PROCESSOR_WORKERS", "3")
+        ),
+        vector_sync_queue_max_size=int(
+            os.getenv("VECTOR_SYNC_QUEUE_MAX_SIZE", "10000")
+        ),
+        # Qdrant settings
+        qdrant_url=os.getenv("QDRANT_URL"),
+        qdrant_location=os.getenv("QDRANT_LOCATION"),
+        qdrant_api_key=os.getenv("QDRANT_API_KEY"),
+        qdrant_collection=os.getenv("QDRANT_COLLECTION", "nextcloud_content"),
+        # Ollama 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")),
+        otel_exporter_otlp_endpoint=os.getenv("OTEL_EXPORTER_OTLP_ENDPOINT"),
+        otel_exporter_verify_ssl=os.getenv("OTEL_EXPORTER_VERIFY_SSL", "false").lower()
+        == "true",
+        otel_service_name=os.getenv("OTEL_SERVICE_NAME", "nextcloud-mcp-server"),
+        otel_traces_sampler=os.getenv("OTEL_TRACES_SAMPLER", "always_on"),
+        otel_traces_sampler_arg=float(os.getenv("OTEL_TRACES_SAMPLER_ARG", "1.0")),
+        log_format=os.getenv("LOG_FORMAT", "text"),
+        log_level=os.getenv("LOG_LEVEL", "INFO"),
+        log_include_trace_context=os.getenv("LOG_INCLUDE_TRACE_CONTEXT", "true").lower()
+        == "true",
     )

nextcloud_mcp_server/controllers/notes_search.py

@@ -12,13 +12,24 @@ class NotesSearchController:
         """
         Search notes using token-based matching with relevance ranking.
         Returns notes sorted by relevance score.
+        If query is empty, returns all notes.
         """
         search_results = []
         query_tokens = self._process_query(query)
 
-        # If empty query after processing, return empty results
+        # If empty query after processing, return all notes
         if not query_tokens:
-            return []
+            async for note in notes:
+                search_results.append(
+                    {
+                        "id": note.get("id"),
+                        "title": note.get("title"),
+                        "category": note.get("category"),
+                        "modified": note.get("modified"),
+                        "_score": None,  # No score for unfiltered results
+                    }
+                )
+            return search_results
 
         # Process and score each note
         async for note in notes:

nextcloud_mcp_server/embedding/__init__.py

@@ -0,0 +1,6 @@
+"""Embedding service package for generating vector embeddings."""
+
+from .service import EmbeddingService, get_embedding_service
+from .simple_provider import SimpleEmbeddingProvider
+
+__all__ = ["EmbeddingService", "get_embedding_service", "SimpleEmbeddingProvider"]

nextcloud_mcp_server/embedding/base.py

@@ -0,0 +1,43 @@
+"""Abstract base class for embedding providers."""
+
+from abc import ABC, abstractmethod
+
+
+class EmbeddingProvider(ABC):
+    """Base class for embedding providers."""
+
+    @abstractmethod
+    async def embed(self, text: str) -> list[float]:
+        """
+        Generate embedding vector for text.
+
+        Args:
+            text: Input text to embed
+
+        Returns:
+            Vector embedding as list of floats
+        """
+        pass
+
+    @abstractmethod
+    async def embed_batch(self, texts: list[str]) -> list[list[float]]:
+        """
+        Generate embeddings for multiple texts (optimized).
+
+        Args:
+            texts: List of texts to embed
+
+        Returns:
+            List of vector embeddings
+        """
+        pass
+
+    @abstractmethod
+    def get_dimension(self) -> int:
+        """
+        Get embedding dimension for this provider.
+
+        Returns:
+            Vector dimension (e.g., 768 for nomic-embed-text)
+        """
+        pass

nextcloud_mcp_server/embedding/ollama_provider.py

@@ -0,0 +1,128 @@
+"""Ollama embedding provider."""
+
+import logging
+
+import httpx
+
+from .base import EmbeddingProvider
+
+logger = logging.getLogger(__name__)
+
+
+class OllamaEmbeddingProvider(EmbeddingProvider):
+    """Ollama embedding provider with TLS support."""
+
+    def __init__(
+        self,
+        base_url: str,
+        model: str = "nomic-embed-text",
+        verify_ssl: bool = True,
+        timeout=httpx.Timeout(timeout=120, connect=5),
+    ):
+        """
+        Initialize Ollama embedding provider.
+
+        Args:
+            base_url: Ollama API base URL (e.g., https://ollama.internal.coutinho.io:443)
+            model: Embedding model name (default: nomic-embed-text)
+            verify_ssl: Verify SSL certificates (default: True)
+        """
+        self.base_url = base_url.rstrip("/")
+        self.model = model
+        self.verify_ssl = verify_ssl
+        self.client = httpx.AsyncClient(verify=verify_ssl, timeout=timeout)
+        self._dimension: int | None = None  # Will be detected dynamically
+        logger.info(
+            f"Initialized Ollama provider: {base_url} (model={model}, verify_ssl={verify_ssl})"
+        )
+
+        self._check_model_is_loaded(autoload=True)
+
+    async def embed(self, text: str) -> list[float]:
+        """
+        Generate embedding vector for text.
+
+        Args:
+            text: Input text to embed
+
+        Returns:
+            Vector embedding as list of floats
+        """
+        response = await self.client.post(
+            f"{self.base_url}/api/embeddings",
+            json={"model": self.model, "prompt": text},
+        )
+        response.raise_for_status()
+        return response.json()["embedding"]
+
+    async def embed_batch(self, texts: list[str]) -> list[list[float]]:
+        """
+        Generate embeddings for multiple texts (batched requests).
+
+        Note: Ollama doesn't have native batch API, so we send requests sequentially.
+        For better performance with large batches, consider using asyncio.gather().
+
+        Args:
+            texts: List of texts to embed
+
+        Returns:
+            List of vector embeddings
+        """
+        embeddings = []
+        for text in texts:
+            embedding = await self.embed(text)
+            embeddings.append(embedding)
+        return embeddings
+
+    async def _detect_dimension(self):
+        """
+        Detect embedding dimension by generating a test embedding.
+
+        This method queries the model to determine the actual dimension
+        instead of relying on hardcoded values.
+        """
+        if self._dimension is None:
+            logger.debug(f"Detecting embedding dimension for model {self.model}...")
+            test_embedding = await self.embed("test")
+            self._dimension = len(test_embedding)
+            logger.info(
+                f"Detected embedding dimension: {self._dimension} for model {self.model}"
+            )
+
+    def get_dimension(self) -> int:
+        """
+        Get embedding dimension.
+
+        Returns:
+            Vector dimension for the configured model
+
+        Raises:
+            RuntimeError: If dimension not detected yet (call _detect_dimension first)
+        """
+        if self._dimension is None:
+            raise RuntimeError(
+                f"Embedding dimension not detected yet for model {self.model}. "
+                "Call _detect_dimension() first or generate an embedding."
+            )
+        return self._dimension
+
+    def _check_model_is_loaded(self, autoload: bool = True):
+        response = httpx.get(f"{self.base_url}/api/tags")
+        response.raise_for_status()
+
+        models = [model["name"] for model in response.json().get("models", [])]
+        logger.info("Ollama has following models pre-loaded: %s", models)
+
+        if (self.model not in models) and autoload:
+            logger.warning(
+                "Embedding model '%s' not yet available in ollama, attempting to pull now...",
+                self.model,
+            )
+            response = httpx.post(
+                f"{self.base_url}/api/pull", json={"model": self.model}
+            )
+            response.raise_for_status()
+
+    async def close(self):
+        """Close HTTP client."""
+        await self.client.aclose()

nextcloud_mcp_server/embedding/service.py

@@ -0,0 +1,111 @@
+"""Embedding service with provider detection."""
+
+import logging
+import os
+
+from .base import EmbeddingProvider
+from .ollama_provider import OllamaEmbeddingProvider
+from .simple_provider import SimpleEmbeddingProvider
+
+logger = logging.getLogger(__name__)
+
+
+class EmbeddingService:
+    """Unified embedding service with automatic provider detection."""
+
+    def __init__(self):
+        """Initialize embedding service with auto-detected provider."""
+        self.provider = self._detect_provider()
+
+    def _detect_provider(self) -> EmbeddingProvider:
+        """
+        Auto-detect available embedding provider.
+
+        Checks environment variables in order:
+        1. OLLAMA_BASE_URL - Use Ollama provider (production)
+        2. OPENAI_API_KEY - Use OpenAI provider (future)
+        3. Fallback to SimpleEmbeddingProvider (testing/development)
+
+        Returns:
+            Configured embedding provider
+        """
+        # Ollama provider (production)
+        ollama_url = os.getenv("OLLAMA_BASE_URL")
+        if ollama_url:
+            logger.info(f"Using Ollama embedding provider: {ollama_url}")
+            return OllamaEmbeddingProvider(
+                base_url=ollama_url,
+                model=os.getenv("OLLAMA_EMBEDDING_MODEL", "nomic-embed-text"),
+                verify_ssl=os.getenv("OLLAMA_VERIFY_SSL", "true").lower() == "true",
+            )
+
+        # OpenAI provider (future implementation)
+        # openai_key = os.getenv("OPENAI_API_KEY")
+        # if openai_key:
+        #     return OpenAIEmbeddingProvider(api_key=openai_key)
+
+        # Fallback to simple provider for development/testing
+        logger.warning(
+            "No embedding provider configured (OLLAMA_BASE_URL or OPENAI_API_KEY not set). "
+            "Using SimpleEmbeddingProvider for testing/development. "
+            "For production, configure an external embedding service."
+        )
+        return SimpleEmbeddingProvider(dimension=384)
+
+    async def embed(self, text: str) -> list[float]:
+        """
+        Generate embedding vector for text.
+
+        Args:
+            text: Input text to embed
+
+        Returns:
+            Vector embedding as list of floats
+        """
+        return await self.provider.embed(text)
+
+    async def embed_batch(self, texts: list[str]) -> list[list[float]]:
+        """
+        Generate embeddings for multiple texts.
+
+        Args:
+            texts: List of texts to embed
+
+        Returns:
+            List of vector embeddings
+        """
+        return await self.provider.embed_batch(texts)
+
+    def get_dimension(self) -> int:
+        """
+        Get embedding dimension.
+
+        Returns:
+            Vector dimension
+        """
+        return self.provider.get_dimension()
+
+    async def close(self):
+        """Close provider resources."""
+        if hasattr(self.provider, "close") and callable(
+            getattr(self.provider, "close")
+        ):
+            close_method = getattr(self.provider, "close")
+            await close_method()
+
+
+# Singleton instance
+_embedding_service: EmbeddingService | None = None
+
+
+def get_embedding_service() -> EmbeddingService:
+    """
+    Get singleton embedding service instance.
+
+    Returns:
+        Global EmbeddingService instance
+    """
+    global _embedding_service
+    if _embedding_service is None:
+        _embedding_service = EmbeddingService()
+    return _embedding_service

nextcloud_mcp_server/embedding/simple_provider.py

@@ -0,0 +1,123 @@
+"""Simple in-process embedding provider for testing.
+
+This provider uses a basic TF-IDF-like approach with feature hashing to generate
+deterministic embeddings without requiring external services. Suitable for testing
+but not for production use.
+"""
+
+import hashlib
+import math
+import re
+from collections import Counter
+
+from .base import EmbeddingProvider
+
+
+class SimpleEmbeddingProvider(EmbeddingProvider):
+    """Simple deterministic embedding provider using feature hashing.
+
+    This implementation:
+    - Tokenizes text into words
+    - Uses feature hashing to map words to fixed-size vectors
+    - Applies TF-IDF-like weighting
+    - Normalizes vectors to unit length
+
+    Not suitable for production but good for testing semantic search infrastructure.
+    """
+
+    def __init__(self, dimension: int = 384):
+        """Initialize simple embedding provider.
+
+        Args:
+            dimension: Embedding dimension (default: 384)
+        """
+        self.dimension = dimension
+
+    def _tokenize(self, text: str) -> list[str]:
+        """Tokenize text into lowercase words.
+
+        Args:
+            text: Input text
+
+        Returns:
+            List of lowercase word tokens
+        """
+        # Simple word tokenization
+        text = text.lower()
+        words = re.findall(r"\b\w+\b", text)
+        return words
+
+    def _hash_word(self, word: str) -> int:
+        """Hash word to dimension index.
+
+        Args:
+            word: Word to hash
+
+        Returns:
+            Index in range [0, dimension)
+        """
+        hash_bytes = hashlib.md5(word.encode()).digest()
+        hash_int = int.from_bytes(hash_bytes[:4], byteorder="big")
+        return hash_int % self.dimension
+
+    def _embed_single(self, text: str) -> list[float]:
+        """Generate embedding for single text.
+
+        Args:
+            text: Input text
+
+        Returns:
+            Normalized embedding vector
+        """
+        tokens = self._tokenize(text)
+        if not tokens:
+            return [0.0] * self.dimension
+
+        # Count term frequencies
+        term_freq = Counter(tokens)
+
+        # Initialize vector
+        vector = [0.0] * self.dimension
+
+        # Apply TF weighting with feature hashing
+        for word, count in term_freq.items():
+            idx = self._hash_word(word)
+            # Simple TF weighting: log(1 + count)
+            vector[idx] += math.log1p(count)
+
+        # Normalize to unit length
+        norm = math.sqrt(sum(x * x for x in vector))
+        if norm > 0:
+            vector = [x / norm for x in vector]
+
+        return vector
+
+    async def embed(self, text: str) -> list[float]:
+        """Generate embedding vector for text.
+
+        Args:
+            text: Input text to embed
+
+        Returns:
+            Vector embedding as list of floats
+        """
+        return self._embed_single(text)
+
+    async def embed_batch(self, texts: list[str]) -> list[list[float]]:
+        """Generate embeddings for multiple texts.
+
+        Args:
+            texts: List of texts to embed
+
+        Returns:
+            List of vector embeddings
+        """
+        return [self._embed_single(text) for text in texts]
+
+    def get_dimension(self) -> int:
+        """Get embedding dimension.
+
+        Returns:
+            Vector dimension
+        """
+        return self.dimension

nextcloud_mcp_server/models/semantic.py

@@ -0,0 +1,109 @@
+"""Pydantic models for semantic search responses."""
+
+from typing import List, Optional
+
+from pydantic import BaseModel, Field
+
+from .base import BaseResponse
+
+
+class SemanticSearchResult(BaseModel):
+    """Model for semantic search results with additional metadata."""
+
+    id: int = Field(description="Document ID")
+    doc_type: str = Field(
+        description="Document type (note, calendar_event, deck_card, etc.)"
+    )
+    title: str = Field(description="Document title")
+    category: str = Field(
+        default="", description="Document category (notes) or location (calendar)"
+    )
+    excerpt: str = Field(description="Excerpt from matching chunk")
+    score: float = Field(description="Semantic similarity score (0-1)")
+    chunk_index: int = Field(description="Index of matching chunk in document")
+    total_chunks: int = Field(description="Total number of chunks in document")
+
+
+class SemanticSearchResponse(BaseResponse):
+    """Response model for semantic search across all indexed Nextcloud apps."""
+
+    results: List[SemanticSearchResult] = Field(
+        description="Semantic search results with similarity scores"
+    )
+    query: str = Field(description="The search query used")
+    total_found: int = Field(description="Total number of documents found")
+    search_method: str = Field(
+        default="semantic", description="Search method used (semantic or hybrid)"
+    )
+
+
+class SamplingSearchResponse(BaseResponse):
+    """Response from semantic search with LLM-generated answer via MCP sampling.
+
+    This response includes both a generated natural language answer (created by
+    the MCP client's LLM via sampling) and the source documents used to generate
+    that answer. Users can read the answer for quick information and review
+    sources for verification and deeper exploration.
+
+    Attributes:
+        query: The original user query
+        generated_answer: Natural language answer generated by client's LLM
+        sources: List of semantic search results used as context
+        total_found: Total number of matching documents found
+        search_method: Always "semantic_sampling" for this response type
+        model_used: Name of model that generated the answer (e.g., "claude-3-5-sonnet")
+        stop_reason: Why generation stopped ("endTurn", "maxTokens", etc.)
+    """
+
+    query: str = Field(..., description="Original user query")
+    generated_answer: str = Field(
+        ..., description="LLM-generated answer based on retrieved documents"
+    )
+    sources: List[SemanticSearchResult] = Field(
+        default_factory=list,
+        description="Source documents with excerpts and relevance scores",
+    )
+    total_found: int = Field(..., description="Total matching documents")
+    search_method: str = Field(
+        default="semantic_sampling", description="Search method used"
+    )
+    model_used: Optional[str] = Field(
+        default=None, description="Model that generated the answer"
+    )
+    stop_reason: Optional[str] = Field(
+        default=None, description="Reason generation stopped"
+    )
+
+
+class VectorSyncStatusResponse(BaseResponse):
+    """Response for vector sync status.
+
+    Provides information about the current state of vector sync,
+    including how many documents are indexed and how many are pending.
+
+    Attributes:
+        indexed_count: Number of documents in Qdrant vector database
+        pending_count: Number of documents in processing queue
+        status: Current sync status ("idle" or "syncing")
+        enabled: Whether vector sync is enabled
+    """
+
+    indexed_count: int = Field(
+        default=0, description="Number of documents indexed in vector database"
+    )
+    pending_count: int = Field(
+        default=0, description="Number of documents pending processing"
+    )
+    status: str = Field(
+        default="disabled",
+        description='Sync status: "idle", "syncing", or "disabled"',
+    )
+    enabled: bool = Field(default=False, description="Whether vector sync is enabled")
+
+
+__all__ = [
+    "SemanticSearchResult",
+    "SemanticSearchResponse",
+    "SamplingSearchResponse",
+    "VectorSyncStatusResponse",
+]

nextcloud_mcp_server/observability/__init__.py

@@ -0,0 +1,31 @@
+"""
+Observability module for the Nextcloud MCP Server.
+
+This module provides:
+- Prometheus metrics collection
+- OpenTelemetry distributed tracing
+- Enhanced structured logging with trace correlation
+- Monitoring middleware for Starlette/FastAPI
+
+Usage:
+    from nextcloud_mcp_server.observability import setup_observability
+
+    # In app.py lifespan
+    setup_observability(app, config)
+"""
+
+from nextcloud_mcp_server.observability.logging_config import (
+    get_uvicorn_logging_config,
+    setup_logging,
+)
+from nextcloud_mcp_server.observability.metrics import setup_metrics
+from nextcloud_mcp_server.observability.middleware import ObservabilityMiddleware
+from nextcloud_mcp_server.observability.tracing import setup_tracing
+
+__all__ = [
+    "setup_logging",
+    "get_uvicorn_logging_config",
+    "setup_metrics",
+    "setup_tracing",
+    "ObservabilityMiddleware",
+]

nextcloud_mcp_server/observability/logging_config.py

@@ -0,0 +1,332 @@
+"""
+Enhanced logging configuration for the Nextcloud MCP Server.
+
+This module provides:
+- Structured JSON logging with python-json-logger
+- Trace context injection (trace_id, span_id) for correlation with distributed traces
+- Configurable log formats (JSON or text)
+- Log level configuration per component
+"""
+
+import logging
+import sys
+from typing import Any
+
+from pythonjsonlogger.json import JsonFormatter
+
+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",
+                "/app/vector-sync/status",
+            ]
+        )
+
+
+class TraceContextFormatter(JsonFormatter):
+    """
+    JSON formatter that injects OpenTelemetry trace context into log records.
+
+    This allows logs to be correlated with distributed traces by including
+    trace_id and span_id in each log entry.
+    """
+
+    def add_fields(
+        self,
+        log_record: dict[str, Any],
+        record: logging.LogRecord,
+        message_dict: dict[str, Any],
+    ) -> None:
+        """
+        Add custom fields to the log record, including trace context.
+
+        Args:
+            log_record: Dictionary to be serialized as JSON
+            record: LogRecord instance
+            message_dict: Dictionary of extra fields from log call
+        """
+        # Call parent to add standard fields
+        super().add_fields(log_record, record, message_dict)
+
+        # Add trace context if available
+        trace_context = get_trace_context()
+        if trace_context:
+            log_record["trace_id"] = trace_context.get("trace_id")
+            log_record["span_id"] = trace_context.get("span_id")
+
+        # Add standard fields with consistent naming
+        log_record["timestamp"] = self.formatTime(record)
+        log_record["level"] = record.levelname
+        log_record["logger"] = record.name
+        log_record["message"] = record.getMessage()
+
+        # Include exception info if present
+        if record.exc_info:
+            log_record["exception"] = self.formatException(record.exc_info)
+
+
+class TraceContextTextFormatter(logging.Formatter):
+    """
+    Text formatter that includes OpenTelemetry trace context.
+
+    Format: [LEVEL] [timestamp] logger - message [trace_id=xxx span_id=yyy]
+    """
+
+    def format(self, record: logging.LogRecord) -> str:
+        """
+        Format log record with trace context.
+
+        Args:
+            record: LogRecord instance
+
+        Returns:
+            Formatted log string
+        """
+        # Format base message
+        base_message = super().format(record)
+
+        # Add trace context if available
+        trace_context = get_trace_context()
+        if trace_context:
+            trace_id = trace_context.get("trace_id", "")
+            span_id = trace_context.get("span_id", "")
+            return f"{base_message} [trace_id={trace_id} span_id={span_id}]"
+
+        return base_message
+
+
+def setup_logging(
+    log_format: str = "json",
+    log_level: str = "INFO",
+    include_trace_context: bool = True,
+) -> None:
+    """
+    Configure logging for the Nextcloud MCP Server.
+
+    Args:
+        log_format: "json" for JSON logging, "text" for human-readable text (default: "json")
+        log_level: Minimum log level (DEBUG, INFO, WARNING, ERROR, CRITICAL) (default: "INFO")
+        include_trace_context: Whether to include trace context in logs (default: True)
+    """
+    # Get root logger
+    root_logger = logging.getLogger()
+    root_logger.setLevel(getattr(logging, log_level.upper(), logging.INFO))
+
+    # Remove existing handlers
+    root_logger.handlers.clear()
+
+    # Create console handler
+    console_handler = logging.StreamHandler(sys.stdout)
+    console_handler.setLevel(getattr(logging, log_level.upper(), logging.INFO))
+
+    # Configure formatter based on format preference
+    if log_format.lower() == "json":
+        if include_trace_context:
+            formatter = TraceContextFormatter(
+                "%(timestamp)s %(level)s %(name)s %(message)s",
+                datefmt="%Y-%m-%dT%H:%M:%S",
+            )
+        else:
+            formatter = JsonFormatter(
+                "%(timestamp)s %(level)s %(name)s %(message)s",
+                datefmt="%Y-%m-%dT%H:%M:%S",
+            )
+    else:  # text format
+        if include_trace_context:
+            formatter = TraceContextTextFormatter(
+                "%(levelname)s [%(asctime)s] %(name)s - %(message)s",
+                datefmt="%Y-%m-%d %H:%M:%S",
+            )
+        else:
+            formatter = logging.Formatter(
+                "%(levelname)s [%(asctime)s] %(name)s - %(message)s",
+                datefmt="%Y-%m-%d %H:%M:%S",
+            )
+
+    console_handler.setFormatter(formatter)
+    root_logger.addHandler(console_handler)
+
+    # Configure specific logger levels
+    configure_component_loggers(log_level)
+
+    root_logger.info(
+        f"Logging configured: format={log_format}, level={log_level}, "
+        f"trace_context={include_trace_context}"
+    )
+
+
+def configure_component_loggers(default_level: str = "INFO") -> None:
+    """
+    Configure log levels for specific components.
+
+    This allows fine-grained control over logging verbosity for different
+    parts of the application.
+
+    Args:
+        default_level: Default log level for most components
+    """
+    # Map of logger names to log levels
+    logger_levels = {
+        # Application loggers
+        "nextcloud_mcp_server": default_level,
+        "nextcloud_mcp_server.server": default_level,
+        "nextcloud_mcp_server.client": default_level,
+        "nextcloud_mcp_server.auth": default_level,
+        "nextcloud_mcp_server.observability": default_level,
+        # HTTP client loggers (less verbose by default)
+        "httpx": "WARNING",
+        "httpcore": "WARNING",
+        # Server loggers
+        "uvicorn": "INFO",
+        "uvicorn.access": "INFO",
+        "uvicorn.error": "INFO",
+        # MCP framework
+        "mcp": "INFO",
+        # OpenTelemetry (less verbose)
+        "opentelemetry": "WARNING",
+    }
+
+    for logger_name, level in logger_levels.items():
+        logger = logging.getLogger(logger_name)
+        logger.setLevel(getattr(logging, level.upper(), logging.INFO))
+
+
+def get_logger(name: str) -> logging.Logger:
+    """
+    Get a logger instance for a specific module.
+
+    This is a convenience function that wraps logging.getLogger()
+    to ensure consistent logger configuration.
+
+    Args:
+        name: Logger name (typically __name__)
+
+    Returns:
+        Logger instance
+    """
+    return logging.getLogger(name)
+
+
+def get_uvicorn_logging_config(
+    log_format: str = "json",
+    log_level: str = "INFO",
+    include_trace_context: bool = True,
+) -> dict:
+    """
+    Get uvicorn-compatible logging configuration.
+
+    This creates a logging config dict that uvicorn can use while maintaining
+    our observability setup (JSON format, trace context, etc.).
+
+    Args:
+        log_format: "json" or "text"
+        log_level: Minimum log level
+        include_trace_context: Whether to include trace IDs in logs
+
+    Returns:
+        Logging config dict compatible with uvicorn's log_config parameter
+    """
+    # Determine formatter class based on format and trace context
+    if log_format.lower() == "json":
+        if include_trace_context:
+            formatter_class = "nextcloud_mcp_server.observability.logging_config.TraceContextFormatter"
+        else:
+            formatter_class = "pythonjsonlogger.json.JsonFormatter"
+        format_string = "%(timestamp)s %(level)s %(name)s %(message)s"
+    else:
+        if include_trace_context:
+            formatter_class = "nextcloud_mcp_server.observability.logging_config.TraceContextTextFormatter"
+        else:
+            formatter_class = "logging.Formatter"
+        format_string = "%(levelname)s [%(asctime)s] %(name)s - %(message)s"
+
+    return {
+        "version": 1,
+        "disable_existing_loggers": False,
+        "formatters": {
+            "default": {
+                "()": formatter_class,
+                "format": format_string,
+                "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": {
+            "": {
+                "handlers": ["default"],
+                "level": log_level.upper(),
+            },
+            "uvicorn": {
+                "handlers": ["default"],
+                "level": "INFO",
+                "propagate": False,
+            },
+            "uvicorn.access": {
+                "handlers": ["access"],
+                "level": "INFO",
+                "propagate": False,
+            },
+            "uvicorn.error": {
+                "handlers": ["default"],
+                "level": "INFO",
+                "propagate": False,
+            },
+            "httpx": {
+                "handlers": ["default"],
+                "level": "WARNING",
+                "propagate": False,
+            },
+            "httpcore": {
+                "handlers": ["default"],
+                "level": "WARNING",
+                "propagate": False,
+            },
+            "opentelemetry": {
+                "handlers": ["default"],
+                "level": "WARNING",
+                "propagate": False,
+            },
+        },
+    }

nextcloud_mcp_server/observability/metrics.py

@@ -0,0 +1,443 @@
+"""
+Prometheus metrics for the Nextcloud MCP Server.
+
+This module defines all Prometheus metrics for monitoring server health, performance,
+and resource usage. Metrics are organized by category:
+
+- HTTP Server Metrics (RED: Rate, Errors, Duration)
+- MCP Tool Metrics (per-tool invocation tracking)
+- MCP Resource Metrics
+- Nextcloud API Client Metrics
+- OAuth Flow Metrics
+- Vector Sync Metrics (conditional on feature flag)
+- Database Operation Metrics
+- External Dependency Health Metrics
+"""
+
+import logging
+
+from prometheus_client import (
+    Counter,
+    Gauge,
+    Histogram,
+    start_http_server,
+)
+
+logger = logging.getLogger(__name__)
+
+# =============================================================================
+# HTTP Server Metrics (RED + System)
+# =============================================================================
+
+http_requests_total = Counter(
+    "mcp_http_requests_total",
+    "Total HTTP requests received",
+    ["method", "endpoint", "status_code"],
+)
+
+http_request_duration_seconds = Histogram(
+    "mcp_http_request_duration_seconds",
+    "HTTP request latency in seconds",
+    ["method", "endpoint"],
+    buckets=(0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1.0, 2.5, 5.0, 10.0),
+)
+
+http_requests_in_progress = Gauge(
+    "mcp_http_requests_in_progress",
+    "Number of HTTP requests currently being processed",
+    ["method", "endpoint"],
+)
+
+# =============================================================================
+# MCP Tool Metrics
+# =============================================================================
+
+mcp_tool_calls_total = Counter(
+    "mcp_tool_calls_total",
+    "Total MCP tool invocations",
+    ["tool_name", "status"],  # status: success | error
+)
+
+mcp_tool_duration_seconds = Histogram(
+    "mcp_tool_duration_seconds",
+    "MCP tool execution duration in seconds",
+    ["tool_name"],
+    buckets=(0.01, 0.05, 0.1, 0.25, 0.5, 1.0, 2.5, 5.0, 10.0, 30.0),
+)
+
+mcp_tool_errors_total = Counter(
+    "mcp_tool_errors_total",
+    "Total MCP tool errors by type",
+    ["tool_name", "error_type"],
+)
+
+# =============================================================================
+# MCP Resource Metrics
+# =============================================================================
+
+mcp_resource_requests_total = Counter(
+    "mcp_resource_requests_total",
+    "Total MCP resource requests",
+    ["resource_uri", "status"],
+)
+
+mcp_resource_duration_seconds = Histogram(
+    "mcp_resource_duration_seconds",
+    "MCP resource request duration in seconds",
+    ["resource_uri"],
+    buckets=(0.01, 0.05, 0.1, 0.25, 0.5, 1.0, 2.5),
+)
+
+# =============================================================================
+# Nextcloud API Client Metrics
+# =============================================================================
+
+nextcloud_api_requests_total = Counter(
+    "mcp_nextcloud_api_requests_total",
+    "Total Nextcloud API requests",
+    ["app", "method", "status_code"],  # app: notes, calendar, contacts, etc.
+)
+
+nextcloud_api_duration_seconds = Histogram(
+    "mcp_nextcloud_api_duration_seconds",
+    "Nextcloud API request duration in seconds",
+    ["app", "method"],
+    buckets=(0.01, 0.05, 0.1, 0.25, 0.5, 1.0, 2.5, 5.0, 10.0),
+)
+
+nextcloud_api_retries_total = Counter(
+    "mcp_nextcloud_api_retries_total",
+    "Total Nextcloud API retries",
+    ["app", "reason"],  # reason: 429 | timeout | connection_error
+)
+
+# =============================================================================
+# OAuth Flow Metrics
+# =============================================================================
+
+oauth_token_validations_total = Counter(
+    "mcp_oauth_token_validations_total",
+    "Total OAuth token validation attempts",
+    ["method", "result"],  # method: introspect | jwt; result: valid | invalid | error
+)
+
+oauth_token_exchange_total = Counter(
+    "mcp_oauth_token_exchange_total",
+    "Total OAuth token exchange operations (RFC 8693)",
+    ["status"],  # status: success | error
+)
+
+oauth_token_cache_hits_total = Counter(
+    "mcp_oauth_token_cache_hits_total",
+    "Total OAuth token cache lookups",
+    ["hit"],  # hit: true | false
+)
+
+oauth_refresh_token_operations_total = Counter(
+    "mcp_oauth_refresh_token_operations_total",
+    "Total refresh token storage operations",
+    [
+        "operation",
+        "status",
+    ],  # operation: store | retrieve | delete; status: success | error
+)
+
+# =============================================================================
+# Vector Sync Metrics (optional feature)
+# =============================================================================
+
+vector_sync_documents_scanned_total = Counter(
+    "mcp_vector_sync_documents_scanned_total",
+    "Total documents scanned for vector sync",
+)
+
+vector_sync_documents_processed_total = Counter(
+    "mcp_vector_sync_documents_processed_total",
+    "Total documents processed for vector sync",
+    ["status"],  # status: success | error
+)
+
+vector_sync_processing_duration_seconds = Histogram(
+    "mcp_vector_sync_processing_duration_seconds",
+    "Document processing duration in seconds",
+    buckets=(0.1, 0.5, 1.0, 2.5, 5.0, 10.0, 30.0, 60.0),
+)
+
+vector_sync_queue_size = Gauge(
+    "mcp_vector_sync_queue_size",
+    "Current number of documents in processing queue",
+)
+
+qdrant_operations_total = Counter(
+    "mcp_qdrant_operations_total",
+    "Total Qdrant vector database operations",
+    [
+        "operation",
+        "status",
+    ],  # operation: upsert | search | delete; status: success | error
+)
+
+# =============================================================================
+# Database Metrics
+# =============================================================================
+
+db_operations_total = Counter(
+    "mcp_db_operations_total",
+    "Total database operations",
+    ["db", "operation", "status"],  # db: sqlite | qdrant; operation varies
+)
+
+db_operation_duration_seconds = Histogram(
+    "mcp_db_operation_duration_seconds",
+    "Database operation duration in seconds",
+    ["db", "operation"],
+    buckets=(0.001, 0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1.0),
+)
+
+# =============================================================================
+# External Dependency Health Metrics
+# =============================================================================
+
+dependency_health = Gauge(
+    "mcp_dependency_health",
+    "External dependency health status (1=up, 0=down)",
+    ["dependency"],  # dependency: nextcloud | keycloak | qdrant | unstructured
+)
+
+dependency_check_duration_seconds = Histogram(
+    "mcp_dependency_check_duration_seconds",
+    "Dependency health check duration in seconds",
+    ["dependency"],
+    buckets=(0.01, 0.05, 0.1, 0.25, 0.5, 1.0, 2.5),
+)
+
+# =============================================================================
+# Metrics Setup and HTTP Handler
+# =============================================================================
+
+
+def setup_metrics(port: int = 9090) -> None:
+    """
+    Initialize Prometheus metrics collection and start HTTP server.
+
+    Starts a dedicated HTTP server on the specified port to serve metrics.
+    This server runs in a separate thread and is isolated from the main application.
+
+    Args:
+        port: Port to serve metrics on (default: 9090)
+
+    Note:
+        Metrics endpoint (/metrics) is ONLY accessible on this dedicated port,
+        not on the main application HTTP port. This is a security best practice
+        to prevent external exposure of metrics.
+    """
+    try:
+        start_http_server(port)
+        logger.info(f"Prometheus metrics server started on port {port}")
+    except OSError as e:
+        if "Address already in use" in str(e):
+            logger.warning(
+                f"Metrics port {port} already in use (metrics server likely already running)"
+            )
+        else:
+            logger.error(f"Failed to start metrics server on port {port}: {e}")
+            raise
+
+
+# =============================================================================
+# Convenience Functions for Common Metric Updates
+# =============================================================================
+
+
+def record_tool_call(tool_name: str, duration: float, status: str = "success") -> None:
+    """
+    Record metrics for an MCP tool call.
+
+    Args:
+        tool_name: Name of the MCP tool
+        duration: Execution duration in seconds
+        status: "success" or "error"
+    """
+    mcp_tool_calls_total.labels(tool_name=tool_name, status=status).inc()
+    mcp_tool_duration_seconds.labels(tool_name=tool_name).observe(duration)
+
+
+def record_tool_error(tool_name: str, error_type: str) -> None:
+    """
+    Record an MCP tool error.
+
+    Args:
+        tool_name: Name of the MCP tool
+        error_type: Type of error (e.g., "HTTPStatusError", "ValueError")
+    """
+    mcp_tool_errors_total.labels(tool_name=tool_name, error_type=error_type).inc()
+
+
+def record_nextcloud_api_call(
+    app: str,
+    method: str,
+    status_code: int,
+    duration: float,
+) -> None:
+    """
+    Record metrics for a Nextcloud API call.
+
+    Args:
+        app: Nextcloud app name (notes, calendar, contacts, etc.)
+        method: HTTP method (GET, POST, PUT, DELETE, PROPFIND, etc.)
+        status_code: HTTP status code
+        duration: Request duration in seconds
+    """
+    nextcloud_api_requests_total.labels(
+        app=app, method=method, status_code=str(status_code)
+    ).inc()
+    nextcloud_api_duration_seconds.labels(app=app, method=method).observe(duration)
+
+
+def record_nextcloud_api_retry(app: str, reason: str) -> None:
+    """
+    Record a Nextcloud API retry.
+
+    Args:
+        app: Nextcloud app name
+        reason: Retry reason (429, timeout, connection_error)
+    """
+    nextcloud_api_retries_total.labels(app=app, reason=reason).inc()
+
+
+def record_oauth_token_validation(method: str, result: str) -> None:
+    """
+    Record an OAuth token validation.
+
+    Args:
+        method: Validation method ("introspect" or "jwt")
+        result: Validation result ("valid", "invalid", or "error")
+    """
+    oauth_token_validations_total.labels(method=method, result=result).inc()
+
+
+def record_db_operation(
+    db: str, operation: str, duration: float, status: str = "success"
+) -> None:
+    """
+    Record a database operation.
+
+    Args:
+        db: Database type ("sqlite" or "qdrant")
+        operation: Operation type (e.g., "insert", "select", "upsert", "search")
+        duration: Operation duration in seconds
+        status: "success" or "error"
+    """
+    db_operations_total.labels(db=db, operation=operation, status=status).inc()
+    db_operation_duration_seconds.labels(db=db, operation=operation).observe(duration)
+
+
+def set_dependency_health(dependency: str, is_healthy: bool) -> None:
+    """
+    Update external dependency health status.
+
+    Args:
+        dependency: Dependency name (nextcloud, keycloak, qdrant, unstructured)
+        is_healthy: True if dependency is healthy, False otherwise
+    """
+    dependency_health.labels(dependency=dependency).set(1 if is_healthy else 0)
+
+
+def record_dependency_check(dependency: str, duration: float) -> None:
+    """
+    Record a dependency health check duration.
+
+    Args:
+        dependency: Dependency name
+        duration: Check duration in seconds
+    """
+    dependency_check_duration_seconds.labels(dependency=dependency).observe(duration)
+
+
+def record_vector_sync_scan(documents_found: int) -> None:
+    """
+    Record documents scanned during vector sync.
+
+    Args:
+        documents_found: Number of documents discovered in scan
+    """
+    vector_sync_documents_scanned_total.inc(documents_found)
+
+
+def record_vector_sync_processing(duration: float, status: str = "success") -> None:
+    """
+    Record document processing with duration and status.
+
+    Args:
+        duration: Processing duration in seconds
+        status: "success" or "error"
+    """
+    vector_sync_documents_processed_total.labels(status=status).inc()
+    vector_sync_processing_duration_seconds.observe(duration)
+
+
+def record_qdrant_operation(operation: str, status: str = "success") -> None:
+    """
+    Record Qdrant vector database operation.
+
+    Args:
+        operation: Operation type ("upsert", "search", "delete")
+        status: "success" or "error"
+    """
+    qdrant_operations_total.labels(operation=operation, status=status).inc()
+
+
+def update_vector_sync_queue_size(size: int) -> None:
+    """
+    Update vector sync queue size gauge.
+
+    Args:
+        size: Current queue size
+    """
+    vector_sync_queue_size.set(size)
+
+
+# =============================================================================
+# Decorator for Automatic Tool Instrumentation
+# =============================================================================
+
+
+def instrument_tool(func):
+    """
+    Decorator to automatically instrument MCP tool functions with metrics.
+
+    Wraps async tool functions to record execution time and success/error status.
+    Compatible with @mcp.tool() and @require_scopes() decorators.
+
+    Usage:
+        @mcp.tool()
+        @require_scopes("notes:write")
+        @instrument_tool
+        async def nc_notes_create_note(...):
+            ...
+
+    Args:
+        func: The async function to instrument
+
+    Returns:
+        Wrapped function with metrics instrumentation
+    """
+    import functools
+    import time
+
+    @functools.wraps(func)
+    async def wrapper(*args, **kwargs):
+        tool_name = func.__name__
+        start_time = time.time()
+        try:
+            result = await func(*args, **kwargs)
+            duration = time.time() - start_time
+            record_tool_call(tool_name, duration, "success")
+            return result
+        except Exception as e:
+            duration = time.time() - start_time
+            record_tool_call(tool_name, duration, "error")
+            record_tool_error(tool_name, type(e).__name__)
+            raise
+
+    return wrapper

nextcloud_mcp_server/observability/middleware.py

@@ -0,0 +1,222 @@
+"""
+Observability middleware for the Nextcloud MCP Server.
+
+This module provides Starlette middleware that automatically instruments
+HTTP requests with:
+- Prometheus metrics (request count, latency, in-flight requests)
+- OpenTelemetry distributed tracing
+- Request/response timing and error tracking
+"""
+
+import logging
+import time
+from typing import Callable
+
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.requests import Request
+from starlette.responses import Response
+
+from nextcloud_mcp_server.observability.metrics import (
+    http_request_duration_seconds,
+    http_requests_in_progress,
+    http_requests_total,
+)
+from nextcloud_mcp_server.observability.tracing import (
+    add_span_attribute,
+    trace_operation,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class ObservabilityMiddleware(BaseHTTPMiddleware):
+    """
+    Starlette middleware for automatic HTTP request instrumentation.
+
+    This middleware:
+    - Records Prometheus metrics for each request (RED metrics)
+    - Creates OpenTelemetry spans for distributed tracing
+    - Tracks request timing and errors
+    - Handles in-flight request counting
+    """
+
+    async def dispatch(
+        self,
+        request: Request,
+        call_next: Callable,
+    ) -> Response:
+        """
+        Process HTTP request with observability instrumentation.
+
+        Args:
+            request: Starlette request object
+            call_next: Next middleware or route handler
+
+        Returns:
+            Response from downstream handler
+        """
+        # Extract request details
+        method = request.method
+        path = request.url.path
+        endpoint = self._get_endpoint_label(path)
+
+        # Increment in-flight requests counter
+        http_requests_in_progress.labels(method=method, endpoint=endpoint).inc()
+
+        # Record start time
+        start_time = time.time()
+
+        # Skip tracing for health/metrics/polling endpoints to reduce noise
+        should_trace = not (
+            path.startswith("/health/")
+            or path == "/metrics"
+            or path == "/app/vector-sync/status"
+        )
+
+        try:
+            if should_trace:
+                # Create span for request (OpenTelemetry auto-instrumentation will create parent span)
+                with trace_operation(
+                    f"HTTP {method} {endpoint}",
+                    attributes={
+                        "http.method": method,
+                        "http.path": path,
+                        "http.scheme": request.url.scheme,
+                        "http.host": request.url.hostname,
+                    },
+                ):
+                    # Process request
+                    response = await call_next(request)
+
+                    # Add response status to span
+                    add_span_attribute("http.status_code", response.status_code)
+
+                    # Record metrics
+                    duration = time.time() - start_time
+                    self._record_request_metrics(
+                        method=method,
+                        endpoint=endpoint,
+                        status_code=response.status_code,
+                        duration=duration,
+                    )
+
+                    return response
+            else:
+                # No tracing for health/metrics endpoints, but still record metrics
+                response = await call_next(request)
+
+                # Record metrics
+                duration = time.time() - start_time
+                self._record_request_metrics(
+                    method=method,
+                    endpoint=endpoint,
+                    status_code=response.status_code,
+                    duration=duration,
+                )
+
+                return response
+
+        except Exception:
+            # Record error metrics
+            duration = time.time() - start_time
+            self._record_request_metrics(
+                method=method,
+                endpoint=endpoint,
+                status_code=500,  # Internal server error
+                duration=duration,
+            )
+
+            logger.error(
+                f"Request failed: {method} {path}",
+                exc_info=True,
+                extra={
+                    "method": method,
+                    "path": path,
+                    "duration_seconds": duration,
+                },
+            )
+
+            # Re-raise exception to be handled by error middleware
+            raise
+
+        finally:
+            # Decrement in-flight requests counter
+            http_requests_in_progress.labels(method=method, endpoint=endpoint).dec()
+
+    def _get_endpoint_label(self, path: str) -> str:
+        """
+        Get endpoint label for metrics, normalizing dynamic path segments.
+
+        This prevents metric cardinality explosion by grouping similar paths.
+
+        Args:
+            path: Request path
+
+        Returns:
+            Normalized endpoint label
+        """
+        # Health check endpoints
+        if path.startswith("/health/"):
+            return "/health/*"
+
+        # Metrics endpoint
+        if path == "/metrics":
+            return "/metrics"
+
+        # MCP protocol endpoints
+        if path == "/sse" or path.startswith("/sse/"):
+            return "/sse"
+
+        if path == "/messages" or path.startswith("/messages/"):
+            return "/messages"
+
+        # OAuth/OIDC endpoints
+        if path.startswith("/oauth/"):
+            return "/oauth/*"
+
+        if path.startswith("/oidc/"):
+            return "/oidc/*"
+
+        # Catch-all for other paths
+        return path
+
+    def _record_request_metrics(
+        self,
+        method: str,
+        endpoint: str,
+        status_code: int,
+        duration: float,
+    ) -> None:
+        """
+        Record Prometheus metrics for an HTTP request.
+
+        Args:
+            method: HTTP method
+            endpoint: Normalized endpoint label
+            status_code: HTTP status code
+            duration: Request duration in seconds
+        """
+        # Record request count
+        http_requests_total.labels(
+            method=method,
+            endpoint=endpoint,
+            status_code=str(status_code),
+        ).inc()
+
+        # Record request duration
+        http_request_duration_seconds.labels(
+            method=method,
+            endpoint=endpoint,
+        ).observe(duration)
+
+        # Log slow requests (>1 second)
+        if duration > 1.0:
+            logger.warning(
+                f"Slow request: {method} {endpoint} took {duration:.3f}s",
+                extra={
+                    "method": method,
+                    "endpoint": endpoint,
+                    "status_code": status_code,
+                    "duration_seconds": duration,
+                },
+            )

nextcloud_mcp_server/observability/tracing.py

@@ -0,0 +1,367 @@
+"""
+OpenTelemetry distributed tracing for the Nextcloud MCP Server.
+
+This module provides:
+- OpenTelemetry SDK initialization with OTLP exporter
+- Auto-instrumentation for ASGI (Starlette/FastAPI) and httpx
+- Helper functions for creating custom spans
+- Context propagation utilities
+- Span attribute standardization
+"""
+
+import logging
+from contextlib import contextmanager
+from typing import Any
+
+from importlib_metadata import version
+from opentelemetry import trace
+from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
+from opentelemetry.instrumentation.logging import LoggingInstrumentor
+from opentelemetry.sdk.resources import Resource
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import BatchSpanProcessor
+from opentelemetry.trace import Status, StatusCode, Tracer
+
+logger = logging.getLogger(__name__)
+
+# Global tracer instance (initialized in setup_tracing)
+_tracer: Tracer | None = None
+
+# Auto-instrument httpx for Nextcloud API calls
+
+
+def setup_tracing(
+    service_name: str = "nextcloud-mcp-server",
+    otlp_endpoint: str | None = None,
+    otlp_verify_ssl: bool = False,
+    sampling_rate: float = 1.0,
+) -> Tracer:
+    """
+    Initialize OpenTelemetry tracing with OTLP exporter.
+
+    Args:
+        service_name: Service name for traces (default: "nextcloud-mcp-server")
+        otlp_endpoint: OTLP gRPC endpoint (e.g., "http://otel-collector:4317")
+                      If None, tracing is initialized but no exporter is configured
+        otlp_verify_ssl: Enable TLS verification for otlp_endpoint. If True,
+                      `insecure` will eval to False
+        sampling_rate: Sampling rate (0.0-1.0). Default 1.0 (100% sampling)
+
+    Returns:
+        Tracer instance for creating custom spans
+    """
+    global _tracer
+
+    # Create resource with service name
+    resource = Resource.create(
+        {
+            "service.name": service_name,
+            "service.version": version(__package__.split(".")[0]),
+        }
+    )
+
+    # Create tracer provider
+    provider = TracerProvider(resource=resource)
+
+    # Configure OTLP exporter if endpoint is provided
+    if otlp_endpoint:
+        try:
+            otlp_exporter = OTLPSpanExporter(
+                endpoint=otlp_endpoint, insecure=not otlp_verify_ssl
+            )
+            span_processor = BatchSpanProcessor(otlp_exporter)
+            provider.add_span_processor(span_processor)
+            logger.info(
+                f"OpenTelemetry tracing enabled with OTLP endpoint: {otlp_endpoint}"
+            )
+        except Exception as e:
+            logger.warning(
+                f"Failed to initialize OTLP exporter: {e}. Continuing without trace export."
+            )
+    else:
+        logger.info(
+            "OpenTelemetry tracing initialized without OTLP exporter (traces will be generated but not exported)"
+        )
+
+    # Set global tracer provider
+    trace.set_tracer_provider(provider)
+
+    # Auto-instrument logging to inject trace context
+    LoggingInstrumentor().instrument(set_logging_format=True)
+
+    # Get and store tracer
+    _tracer = trace.get_tracer(__name__)
+
+    logger.info(f"OpenTelemetry tracing initialized for service: {service_name}")
+    return _tracer
+
+
+def get_tracer() -> Tracer | None:
+    """
+    Get the global tracer instance.
+
+    Returns:
+        Tracer instance for creating custom spans, or None if tracing is not enabled
+
+    Note:
+        Returns None if setup_tracing() was never called (tracing disabled).
+        Calling code should handle None gracefully.
+    """
+    return _tracer
+
+
+@contextmanager
+def trace_operation(
+    operation_name: str,
+    attributes: dict[str, Any] | None = None,
+    record_exception: bool = True,
+):
+    """
+    Context manager for tracing an operation with automatic error handling.
+
+    Usage:
+        with trace_operation("mcp.tool.nc_notes_create_note", {"note.title": "My Note"}):
+            # Your code here
+            pass
+
+    Args:
+        operation_name: Name of the operation (span name)
+        attributes: Optional attributes to add to the span
+        record_exception: Whether to record exceptions in the span (default: True)
+
+    Yields:
+        Span instance for adding additional attributes (or None if tracing disabled)
+    """
+    tracer = get_tracer()
+
+    # If tracing is not enabled, just yield without creating a span
+    if tracer is None:
+        yield None
+        return
+
+    with tracer.start_as_current_span(operation_name) as span:
+        # Set initial attributes
+        if attributes:
+            for key, value in attributes.items():
+                span.set_attribute(key, value)
+
+        try:
+            yield span
+            span.set_status(Status(StatusCode.OK))
+        except Exception as e:
+            if record_exception:
+                span.record_exception(e)
+            span.set_status(Status(StatusCode.ERROR, str(e)))
+            raise
+
+
+def trace_mcp_tool(tool_name: str, tool_args: dict[str, Any] | None = None):
+    """
+    Create a span for an MCP tool invocation.
+
+    Usage:
+        with trace_mcp_tool("nc_notes_create_note", {"title": "My Note"}):
+            # Tool implementation
+            pass
+
+    Args:
+        tool_name: Name of the MCP tool
+        tool_args: Optional tool arguments (sensitive data will be sanitized)
+
+    Returns:
+        Context manager for the span
+    """
+    attributes = {
+        "mcp.tool.name": tool_name,
+    }
+
+    # Add sanitized tool args (avoid logging sensitive data)
+    if tool_args:
+        # Only include non-sensitive arguments
+        safe_args = {
+            k: v
+            for k, v in tool_args.items()
+            if k not in ("password", "token", "secret", "api_key", "etag")
+        }
+        if safe_args:
+            attributes["mcp.tool.args"] = str(safe_args)
+
+    return trace_operation(f"mcp.tool.{tool_name}", attributes)
+
+
+def trace_nextcloud_api_call(
+    app: str,
+    method: str,
+    path: str | None = None,
+):
+    """
+    Create a span for a Nextcloud API call.
+
+    Usage:
+        with trace_nextcloud_api_call("notes", "POST", "/apps/notes/api/v1/notes"):
+            # API call implementation
+            pass
+
+    Args:
+        app: Nextcloud app name (notes, calendar, contacts, etc.)
+        method: HTTP method (GET, POST, PUT, DELETE, etc.)
+        path: Optional API path
+
+    Returns:
+        Context manager for the span
+    """
+    attributes = {
+        "nextcloud.app": app,
+        "http.method": method,
+    }
+
+    if path:
+        attributes["http.path"] = path
+
+    return trace_operation(f"nextcloud.api.{app}.{method}", attributes)
+
+
+def trace_oauth_operation(operation: str, details: dict[str, Any] | None = None):
+    """
+    Create a span for an OAuth operation.
+
+    Usage:
+        with trace_oauth_operation("token.validate", {"method": "jwt"}):
+            # OAuth validation logic
+            pass
+
+    Args:
+        operation: OAuth operation name (e.g., "token.validate", "token.exchange")
+        details: Optional operation details (sensitive data will be sanitized)
+
+    Returns:
+        Context manager for the span
+    """
+    attributes = {"oauth.operation": operation}
+
+    if details:
+        # Only include non-sensitive details
+        safe_details = {
+            k: v
+            for k, v in details.items()
+            if k not in ("token", "refresh_token", "access_token", "client_secret")
+        }
+        if safe_details:
+            attributes.update(safe_details)
+
+    return trace_operation(f"oauth.{operation}", attributes)
+
+
+def trace_vector_sync_operation(
+    operation: str,
+    document_count: int | None = None,
+):
+    """
+    Create a span for a vector sync operation.
+
+    Usage:
+        with trace_vector_sync_operation("scan", document_count=10):
+            # Vector sync logic
+            pass
+
+    Args:
+        operation: Operation name (scan, process, embed, upsert)
+        document_count: Optional number of documents being processed
+
+    Returns:
+        Context manager for the span
+    """
+    attributes = {"vector_sync.operation": operation}
+
+    if document_count is not None:
+        attributes["vector_sync.document_count"] = document_count
+
+    return trace_operation(f"vector_sync.{operation}", attributes)
+
+
+def trace_db_operation(
+    db: str,
+    operation: str,
+    table: str | None = None,
+):
+    """
+    Create a span for a database operation.
+
+    Usage:
+        with trace_db_operation("sqlite", "insert", "refresh_tokens"):
+            # Database operation
+            pass
+
+    Args:
+        db: Database type (sqlite, qdrant)
+        operation: Operation type (insert, select, update, delete, upsert, search)
+        table: Optional table/collection name
+
+    Returns:
+        Context manager for the span
+    """
+    attributes = {
+        "db.system": db,
+        "db.operation": operation,
+    }
+
+    if table:
+        attributes["db.table"] = table
+
+    return trace_operation(f"db.{db}.{operation}", attributes)
+
+
+def add_span_attribute(key: str, value: Any) -> None:
+    """
+    Add an attribute to the current span (if any).
+
+    Args:
+        key: Attribute key
+        value: Attribute value
+
+    Note:
+        This is a no-op if tracing is not enabled or there's no active span.
+    """
+    if _tracer is None:
+        return  # Tracing not enabled
+    span = trace.get_current_span()
+    if span.is_recording():
+        span.set_attribute(key, value)
+
+
+def add_span_event(name: str, attributes: dict[str, Any] | None = None) -> None:
+    """
+    Add an event to the current span (if any).
+
+    Args:
+        name: Event name
+        attributes: Optional event attributes
+
+    Note:
+        This is a no-op if tracing is not enabled or there's no active span.
+    """
+    if _tracer is None:
+        return  # Tracing not enabled
+    span = trace.get_current_span()
+    if span.is_recording():
+        span.add_event(name, attributes=attributes or {})
+
+
+def get_trace_context() -> dict[str, str]:
+    """
+    Get current trace context as a dictionary.
+
+    Returns:
+        Dictionary with trace_id and span_id (or empty dict if tracing disabled or no active span)
+    """
+    if _tracer is None:
+        return {}  # Tracing not enabled
+
+    span = trace.get_current_span()
+    if span.is_recording():
+        span_context = span.get_span_context()
+        return {
+            "trace_id": format(span_context.trace_id, "032x"),
+            "span_id": format(span_context.span_id, "016x"),
+        }
+    return {}

nextcloud_mcp_server/search/__init__.py

@@ -0,0 +1,33 @@
+"""Search algorithms module for unified multi-algorithm search.
+
+This module provides a unified interface for different search algorithms:
+- Semantic search (vector similarity)
+- Keyword search (token-based matching)
+- Fuzzy search (character overlap)
+- Hybrid search (RRF fusion of multiple algorithms)
+
+All algorithms share the same interface and can be used interchangeably by both
+MCP tools and the visualization pane.
+"""
+
+from nextcloud_mcp_server.search.algorithms import (
+    NextcloudClientProtocol,
+    SearchAlgorithm,
+    SearchResult,
+    get_indexed_doc_types,
+)
+from nextcloud_mcp_server.search.fuzzy import FuzzySearchAlgorithm
+from nextcloud_mcp_server.search.hybrid import HybridSearchAlgorithm
+from nextcloud_mcp_server.search.keyword import KeywordSearchAlgorithm
+from nextcloud_mcp_server.search.semantic import SemanticSearchAlgorithm
+
+__all__ = [
+    "NextcloudClientProtocol",
+    "SearchAlgorithm",
+    "SearchResult",
+    "get_indexed_doc_types",
+    "SemanticSearchAlgorithm",
+    "KeywordSearchAlgorithm",
+    "FuzzySearchAlgorithm",
+    "HybridSearchAlgorithm",
+]

nextcloud_mcp_server/search/algorithms.py

@@ -0,0 +1,200 @@
+"""Base interfaces and data structures for search algorithms."""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import Any, Protocol, runtime_checkable
+
+
+@runtime_checkable
+class NextcloudClientProtocol(Protocol):
+    """Protocol for Nextcloud client supporting multi-document search.
+
+    This protocol defines the interface that search algorithms need from a
+    Nextcloud client to access documents across different apps (Notes, Files,
+    Calendar, etc.). The client provides access to app-specific sub-clients
+    that handle the actual API calls.
+
+    Document types (e.g., "note", "file", "calendar") are NOT 1:1 with apps.
+    For example, the Notes app specializes in markdown files, while Files/WebDAV
+    handles multiple file types. The abstraction is at the document type level.
+
+    Search algorithms query Qdrant to determine which document types are actually
+    indexed before attempting to access them, enabling graceful cross-app search.
+    """
+
+    username: str
+
+    # App-specific clients that search algorithms dispatch to
+    @property
+    def notes(self) -> Any:
+        """Notes client for accessing note documents."""
+        ...
+
+    @property
+    def webdav(self) -> Any:
+        """WebDAV client for accessing file documents."""
+        ...
+
+    @property
+    def calendar(self) -> Any:
+        """Calendar client for accessing event/task documents."""
+        ...
+
+    @property
+    def contacts(self) -> Any:
+        """Contacts client for accessing contact card documents."""
+        ...
+
+    @property
+    def deck(self) -> Any:
+        """Deck client for accessing deck card documents."""
+        ...
+
+    @property
+    def cookbook(self) -> Any:
+        """Cookbook client for accessing recipe documents."""
+        ...
+
+    @property
+    def tables(self) -> Any:
+        """Tables client for accessing table row documents."""
+        ...
+
+
+async def get_indexed_doc_types(user_id: str) -> set[str]:
+    """Query Qdrant to get actually-indexed document types for a user.
+
+    This enables search algorithms to check which document types are available
+    before attempting to search/verify them, allowing graceful cross-app search.
+
+    Args:
+        user_id: User ID to filter by
+
+    Returns:
+        Set of document type strings (e.g., {"note", "file", "calendar"})
+
+    Example:
+        >>> types = await get_indexed_doc_types("alice")
+        >>> if "note" in types:
+        ...     # Search notes
+    """
+    import logging
+
+    from qdrant_client.models import FieldCondition, Filter, MatchValue
+
+    from nextcloud_mcp_server.config import get_settings
+    from nextcloud_mcp_server.vector.qdrant_client import get_qdrant_client
+
+    logger = logging.getLogger(__name__)
+    settings = get_settings()
+
+    qdrant_client = await get_qdrant_client()
+    collection = settings.get_collection_name()
+
+    # Use scroll to sample documents and extract doc_types
+    # Note: This could be optimized with a facet/aggregation query if Qdrant adds support
+    try:
+        scroll_results, _next_offset = await qdrant_client.scroll(
+            collection_name=collection,
+            scroll_filter=Filter(
+                must=[FieldCondition(key="user_id", match=MatchValue(value=user_id))]
+            ),
+            limit=1000,  # Sample size to discover types
+            with_payload=["doc_type"],
+            with_vectors=False,  # Don't need vectors for type discovery
+        )
+
+        doc_types = {
+            point.payload.get("doc_type")
+            for point in scroll_results
+            if point.payload.get("doc_type")
+        }
+
+        logger.debug(f"Found indexed document types for user {user_id}: {doc_types}")
+        return doc_types
+
+    except Exception as e:
+        logger.warning(f"Failed to query Qdrant for doc_types: {e}")
+        return set()
+
+
+@dataclass
+class SearchResult:
+    """A single search result with metadata and score.
+
+    Attributes:
+        id: Document ID
+        doc_type: Document type (note, file, calendar, contact, etc.)
+        title: Document title
+        excerpt: Content excerpt showing match context
+        score: Relevance score (0.0-1.0, higher is better)
+        metadata: Additional algorithm-specific metadata
+    """
+
+    id: int
+    doc_type: str
+    title: str
+    excerpt: str
+    score: float
+    metadata: dict[str, Any] | None = None
+
+    def __post_init__(self):
+        """Validate score is in valid range."""
+        if not 0.0 <= self.score <= 1.0:
+            raise ValueError(f"Score must be between 0.0 and 1.0, got {self.score}")
+
+
+class SearchAlgorithm(ABC):
+    """Abstract base class for search algorithms.
+
+    All search algorithms must implement the search() method with consistent
+    interface, allowing them to be used interchangeably.
+    """
+
+    @abstractmethod
+    async def search(
+        self,
+        query: str,
+        user_id: str,
+        limit: int = 10,
+        doc_type: str | None = None,
+        **kwargs: Any,
+    ) -> list[SearchResult]:
+        """Execute search with the given parameters.
+
+        Args:
+            query: Search query string
+            user_id: User ID for multi-tenant filtering
+            limit: Maximum number of results to return
+            doc_type: Optional document type filter (note, file, calendar, etc.)
+            **kwargs: Algorithm-specific parameters
+
+        Returns:
+            List of SearchResult objects ranked by relevance
+
+        Raises:
+            McpError: If search fails or configuration is invalid
+        """
+        pass
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """Return algorithm name for identification."""
+        pass
+
+    @property
+    def supports_scoring(self) -> bool:
+        """Whether this algorithm provides meaningful relevance scores.
+
+        Default: True. Override if algorithm doesn't support scoring.
+        """
+        return True
+
+    @property
+    def requires_vector_db(self) -> bool:
+        """Whether this algorithm requires vector database.
+
+        Default: False. Override for semantic search.
+        """
+        return False

nextcloud_mcp_server/search/fuzzy.py

@@ -0,0 +1,219 @@
+"""Fuzzy search algorithm using character overlap matching on Qdrant payload."""
+
+import logging
+from typing import Any
+
+from qdrant_client.models import FieldCondition, Filter, MatchValue
+
+from nextcloud_mcp_server.config import get_settings
+from nextcloud_mcp_server.search.algorithms import SearchAlgorithm, SearchResult
+from nextcloud_mcp_server.vector.qdrant_client import get_qdrant_client
+
+logger = logging.getLogger(__name__)
+
+
+class FuzzySearchAlgorithm(SearchAlgorithm):
+    """Fuzzy search using simple character-based similarity.
+
+    Implements character overlap matching with configurable threshold:
+    - Compares character sets between query and text
+    - Requires configurable % character overlap to match (default: 70%)
+    - Tolerant to typos and minor variations
+    """
+
+    def __init__(self, threshold: float = 0.7):
+        """Initialize fuzzy search algorithm.
+
+        Args:
+            threshold: Minimum character overlap ratio (0-1, default: 0.7)
+        """
+        if not 0.0 <= threshold <= 1.0:
+            raise ValueError(f"Threshold must be between 0.0 and 1.0, got {threshold}")
+        self.threshold = threshold
+
+    @property
+    def name(self) -> str:
+        return "fuzzy"
+
+    async def search(
+        self,
+        query: str,
+        user_id: str,
+        limit: int = 10,
+        doc_type: str | None = None,
+        **kwargs: Any,
+    ) -> list[SearchResult]:
+        """Execute fuzzy search using character overlap on Qdrant payload.
+
+        Queries Qdrant for all indexed documents, then scores based on character
+        overlap in title and excerpt fields. Returns unverified results - access
+        verification should be performed separately at the final output stage.
+
+        Args:
+            query: Search query
+            user_id: User ID for filtering
+            limit: Maximum results to return
+            doc_type: Optional document type filter (None = all types)
+            **kwargs: Additional parameters (threshold override)
+
+        Returns:
+            List of unverified SearchResult objects ranked by character overlap score
+        """
+        settings = get_settings()
+        threshold = kwargs.get("threshold", self.threshold)
+
+        logger.info(
+            f"Fuzzy search: query='{query}', user={user_id}, "
+            f"limit={limit}, threshold={threshold}, doc_type={doc_type}"
+        )
+
+        # Build Qdrant filter
+        filter_conditions = [
+            FieldCondition(key="user_id", match=MatchValue(value=user_id))
+        ]
+        if doc_type:
+            filter_conditions.append(
+                FieldCondition(key="doc_type", match=MatchValue(value=doc_type))
+            )
+
+        # Scroll through Qdrant to get all matching documents
+        qdrant_client = await get_qdrant_client()
+        collection = settings.get_collection_name()
+
+        all_points = []
+        offset = None
+
+        # Scroll through all points matching filter
+        while True:
+            scroll_result, next_offset = await qdrant_client.scroll(
+                collection_name=collection,
+                scroll_filter=Filter(must=filter_conditions),
+                limit=100,  # Batch size
+                offset=offset,
+                with_payload=["doc_id", "doc_type", "title", "excerpt", "chunk_index"],
+                with_vectors=False,  # Don't need vectors
+            )
+
+            all_points.extend(scroll_result)
+
+            if next_offset is None:
+                break
+            offset = next_offset
+
+        logger.debug(f"Retrieved {len(all_points)} points from Qdrant for fuzzy search")
+
+        # Deduplicate by (doc_id, doc_type) - keep first chunk
+        seen_docs = {}
+        for point in all_points:
+            doc_id = int(point.payload["doc_id"])
+            dtype = point.payload.get("doc_type", "note")
+            doc_key = (doc_id, dtype)
+
+            chunk_idx = point.payload.get("chunk_index", 0)
+            if doc_key not in seen_docs or chunk_idx == 0:
+                seen_docs[doc_key] = point
+
+        logger.debug(f"Deduplicated to {len(seen_docs)} unique documents")
+
+        # Score each document based on fuzzy matches
+        scored_results = []
+        query_lower = query.lower()
+
+        for doc_key, point in seen_docs.items():
+            doc_id, dtype = doc_key
+            title = point.payload.get("title", "")
+            excerpt = point.payload.get("excerpt", "")
+
+            # Check title match
+            title_score = self._calculate_char_overlap(query_lower, title.lower())
+
+            # Check excerpt match
+            excerpt_score = self._calculate_char_overlap(query_lower, excerpt.lower())
+
+            # Use best score
+            best_score = max(title_score, excerpt_score)
+
+            if best_score >= threshold:
+                match_location = "title" if title_score >= excerpt_score else "excerpt"
+                scored_results.append(
+                    {
+                        "doc_id": doc_id,
+                        "doc_type": dtype,
+                        "title": title,
+                        "excerpt": excerpt
+                        if excerpt_score >= title_score
+                        else f"Title match: {title}",
+                        "score": best_score,
+                        "match_location": match_location,
+                    }
+                )
+
+        # Sort by score (descending) and limit
+        scored_results.sort(key=lambda x: x["score"], reverse=True)
+        top_results = scored_results[:limit]
+
+        # Return unverified results (verification happens at output stage)
+        final_results = []
+        for result in top_results:
+            final_results.append(
+                SearchResult(
+                    id=result["doc_id"],
+                    doc_type=result["doc_type"],
+                    title=result["title"],
+                    excerpt=result["excerpt"],
+                    score=result["score"],
+                    metadata={"match_location": result["match_location"]},
+                )
+            )
+
+        logger.info(f"Fuzzy search returned {len(final_results)} unverified results")
+        if final_results:
+            result_details = [
+                f"{r.doc_type}_{r.id} (score={r.score:.3f}, title='{r.title}')"
+                for r in final_results[:5]
+            ]
+            logger.debug(f"Top fuzzy results: {', '.join(result_details)}")
+
+        return final_results
+
+    def _calculate_char_overlap(self, query: str, text: str) -> float:
+        """Calculate character overlap ratio between query and text.
+
+        Args:
+            query: Query string (normalized)
+            text: Text to compare (normalized)
+
+        Returns:
+            Overlap ratio (0.0-1.0)
+        """
+        if not query or not text:
+            return 0.0
+
+        # Convert to character sets
+        query_chars = set(query)
+        text_chars = set(text)
+
+        # Calculate overlap
+        overlap = query_chars & text_chars
+        overlap_ratio = len(overlap) / len(query_chars)
+
+        return overlap_ratio
+
+    def _extract_excerpt(self, content: str, max_length: int = 200) -> str:
+        """Extract excerpt from content.
+
+        Args:
+            content: Full document content
+            max_length: Maximum excerpt length
+
+        Returns:
+            Excerpt string
+        """
+        if not content:
+            return ""
+
+        excerpt = content[:max_length].strip()
+        if len(content) > max_length:
+            excerpt += "..."
+
+        return excerpt

nextcloud_mcp_server/search/hybrid.py

@@ -0,0 +1,278 @@
+"""Hybrid search algorithm using Reciprocal Rank Fusion (RRF)."""
+
+import logging
+from collections import defaultdict
+from typing import Any
+
+import anyio
+
+from nextcloud_mcp_server.search.algorithms import SearchAlgorithm, SearchResult
+from nextcloud_mcp_server.search.fuzzy import FuzzySearchAlgorithm
+from nextcloud_mcp_server.search.keyword import KeywordSearchAlgorithm
+from nextcloud_mcp_server.search.semantic import SemanticSearchAlgorithm
+
+logger = logging.getLogger(__name__)
+
+
+class HybridSearchAlgorithm(SearchAlgorithm):
+    """Hybrid search combining multiple algorithms using Reciprocal Rank Fusion.
+
+    Implements RRF from ADR-003 to combine results from:
+    - Semantic search (vector similarity)
+    - Keyword search (token matching)
+    - Fuzzy search (character overlap)
+
+    RRF formula: score = weight / (k + rank)
+    where k=60 (standard value) and rank is 1-indexed position.
+    """
+
+    DEFAULT_RRF_K = 60  # Standard RRF constant
+
+    def __init__(
+        self,
+        semantic_weight: float = 0.5,
+        keyword_weight: float = 0.3,
+        fuzzy_weight: float = 0.2,
+        rrf_k: int = DEFAULT_RRF_K,
+    ):
+        """Initialize hybrid search with algorithm weights.
+
+        Args:
+            semantic_weight: Weight for semantic results (default: 0.5)
+            keyword_weight: Weight for keyword results (default: 0.3)
+            fuzzy_weight: Weight for fuzzy results (default: 0.2)
+            rrf_k: RRF constant for rank decay (default: 60)
+
+        Raises:
+            ValueError: If weights are invalid
+        """
+        # Validate weights
+        if semantic_weight < 0 or keyword_weight < 0 or fuzzy_weight < 0:
+            raise ValueError("Weights must be non-negative")
+
+        total_weight = semantic_weight + keyword_weight + fuzzy_weight
+        if total_weight > 1.0:
+            raise ValueError(f"Weights sum to {total_weight:.2f}, must be ≤1.0")
+
+        if total_weight == 0.0:
+            raise ValueError("At least one weight must be > 0")
+
+        self.semantic_weight = semantic_weight
+        self.keyword_weight = keyword_weight
+        self.fuzzy_weight = fuzzy_weight
+        self.rrf_k = rrf_k
+        self.total_weight = total_weight
+
+        # Initialize sub-algorithms
+        self.semantic = SemanticSearchAlgorithm()
+        self.keyword = KeywordSearchAlgorithm()
+        self.fuzzy = FuzzySearchAlgorithm()
+
+    @property
+    def name(self) -> str:
+        return "hybrid"
+
+    @property
+    def requires_vector_db(self) -> bool:
+        # Requires vector DB if semantic search has non-zero weight
+        return self.semantic_weight > 0
+
+    async def search(
+        self,
+        query: str,
+        user_id: str,
+        limit: int = 10,
+        doc_type: str | None = None,
+        **kwargs: Any,
+    ) -> list[SearchResult]:
+        """Execute hybrid search using RRF to combine algorithms.
+
+        Returns unverified results from combined algorithms. Access verification
+        should be performed separately at the final output stage.
+
+        Args:
+            query: Search query
+            user_id: User ID for filtering
+            limit: Maximum results to return
+            doc_type: Optional document type filter
+            **kwargs: Additional parameters passed to sub-algorithms
+
+        Returns:
+            List of unverified SearchResult objects ranked by RRF combined score
+        """
+        logger.info(
+            f"Hybrid search: query='{query}', user={user_id}, limit={limit}, "
+            f"weights=(semantic={self.semantic_weight}, keyword={self.keyword_weight}, "
+            f"fuzzy={self.fuzzy_weight})"
+        )
+
+        # Prepare algorithm configurations for parallel execution
+        algo_configs = []
+        if self.semantic_weight > 0:
+            algo_configs.append(
+                (
+                    "semantic",
+                    self.semantic.search,
+                    query,
+                    user_id,
+                    limit * 2,
+                    doc_type,
+                    kwargs,
+                )
+            )
+        if self.keyword_weight > 0:
+            algo_configs.append(
+                (
+                    "keyword",
+                    self.keyword.search,
+                    query,
+                    user_id,
+                    limit * 2,
+                    doc_type,
+                    kwargs,
+                )
+            )
+        if self.fuzzy_weight > 0:
+            algo_configs.append(
+                (
+                    "fuzzy",
+                    self.fuzzy.search,
+                    query,
+                    user_id,
+                    limit * 2,
+                    doc_type,
+                    kwargs,
+                )
+            )
+
+        # Pre-allocate results list and extract algorithm names
+        results_list = [None] * len(algo_configs)
+        algo_names = [name for name, *_ in algo_configs]
+
+        async def search_one(
+            index: int,
+            search_func,
+            query_arg: str,
+            user_id_arg: str,
+            limit_arg: int,
+            doc_type_arg: str | None,
+            kwargs_arg: dict,
+        ):
+            """Execute one search algorithm and store result at index."""
+            result = await search_func(
+                query_arg, user_id_arg, limit_arg, doc_type_arg, **kwargs_arg
+            )
+            results_list[index] = result
+
+        # Execute searches in parallel using anyio task group
+        async with anyio.create_task_group() as tg:
+            for idx, (name, search_func, q, uid, lim, dt, kw) in enumerate(
+                algo_configs
+            ):
+                tg.start_soon(search_one, idx, search_func, q, uid, lim, dt, kw)
+
+        # Build results dict
+        algo_results = {}
+        for algo_name, results in zip(algo_names, results_list):
+            algo_results[algo_name] = results
+            logger.debug(f"{algo_name} returned {len(results)} results")
+
+        # Combine using RRF
+        combined_results = self._reciprocal_rank_fusion(
+            algo_results,
+            {
+                "semantic": self.semantic_weight,
+                "keyword": self.keyword_weight,
+                "fuzzy": self.fuzzy_weight,
+            },
+            limit,
+        )
+
+        logger.info(f"Hybrid search returned {len(combined_results)} combined results")
+        if combined_results:
+            result_details = [
+                f"{r.doc_type}_{r.id} (score={r.score:.3f}, title='{r.title}')"
+                for r in combined_results[:5]
+            ]
+            logger.debug(f"Top hybrid results: {', '.join(result_details)}")
+
+        return combined_results
+
+    def _reciprocal_rank_fusion(
+        self,
+        algo_results: dict[str, list[SearchResult]],
+        weights: dict[str, float],
+        limit: int,
+    ) -> list[SearchResult]:
+        """Combine multiple ranked result lists using RRF.
+
+        Args:
+            algo_results: Dict of algorithm_name -> ranked results
+            weights: Dict of algorithm_name -> weight (0-1)
+            limit: Maximum results to return
+
+        Returns:
+            Combined and re-ranked results
+        """
+        # Track RRF scores per document
+        rrf_scores: dict[tuple[int, str], float] = defaultdict(float)
+        # Track best result object for each document
+        best_results: dict[tuple[int, str], SearchResult] = {}
+
+        for algo_name, results in algo_results.items():
+            weight = weights.get(algo_name, 0.0)
+            if weight == 0:
+                continue
+
+            for rank, result in enumerate(results, start=1):
+                doc_key = (result.id, result.doc_type)
+
+                # RRF formula: weight / (k + rank)
+                rrf_score = weight / (self.rrf_k + rank)
+                rrf_scores[doc_key] += rrf_score
+
+                # Track best result object (prefer higher original scores)
+                if doc_key not in best_results:
+                    best_results[doc_key] = result
+                elif result.score > best_results[doc_key].score:
+                    best_results[doc_key] = result
+
+        # Sort by combined RRF score
+        sorted_docs = sorted(
+            rrf_scores.items(),
+            key=lambda x: x[1],
+            reverse=True,
+        )[:limit]
+
+        # Calculate normalization factor to scale RRF scores to 0-1 range
+        # Theoretical max RRF score = total_weight / (rrf_k + 1)
+        # Normalization factor = (rrf_k + 1) / total_weight
+        normalization_factor = (self.rrf_k + 1) / self.total_weight
+
+        # Build final results with normalized RRF scores
+        final_results = []
+        for doc_key, rrf_score in sorted_docs:
+            result = best_results[doc_key]
+
+            # Normalize RRF score to 0-1 range for better user comprehension
+            normalized_score = rrf_score * normalization_factor
+
+            # Create new result with normalized score
+            # Keep original metadata but add RRF details
+            metadata = result.metadata or {}
+            metadata["rrf_score_raw"] = rrf_score  # Original RRF score
+            metadata["original_score"] = result.score  # Original algorithm score
+            metadata["normalization_factor"] = normalization_factor
+
+            final_results.append(
+                SearchResult(
+                    id=result.id,
+                    doc_type=result.doc_type,
+                    title=result.title,
+                    excerpt=result.excerpt,
+                    score=normalized_score,  # Use normalized score (0-1 range)
+                    metadata=metadata,
+                )
+            )
+
+        return final_results

nextcloud_mcp_server/search/keyword.py

@@ -0,0 +1,277 @@
+"""Keyword search algorithm using token-based matching on Qdrant payload (ADR-001)."""
+
+import logging
+from typing import Any
+
+from qdrant_client.models import FieldCondition, Filter, MatchValue
+
+from nextcloud_mcp_server.config import get_settings
+from nextcloud_mcp_server.search.algorithms import SearchAlgorithm, SearchResult
+from nextcloud_mcp_server.vector.qdrant_client import get_qdrant_client
+
+logger = logging.getLogger(__name__)
+
+
+class KeywordSearchAlgorithm(SearchAlgorithm):
+    """Keyword search using token-based matching with weighted scoring.
+
+    Implements token-based search from ADR-001:
+    - Title matches weighted 3x higher than content matches
+    - Case-insensitive token matching
+    - Relevance scoring based on match frequency and location
+    """
+
+    # Weighting constants from ADR-001
+    TITLE_WEIGHT = 3.0
+    CONTENT_WEIGHT = 1.0
+
+    @property
+    def name(self) -> str:
+        return "keyword"
+
+    async def search(
+        self,
+        query: str,
+        user_id: str,
+        limit: int = 10,
+        doc_type: str | None = None,
+        **kwargs: Any,
+    ) -> list[SearchResult]:
+        """Execute keyword search using token matching on Qdrant payload.
+
+        Queries Qdrant for all indexed documents, then scores based on token
+        matches in title and excerpt fields. Returns unverified results - access
+        verification should be performed separately at the final output stage.
+
+        Args:
+            query: Search query to tokenize and match
+            user_id: User ID for filtering
+            limit: Maximum results to return
+            doc_type: Optional document type filter (None = all types)
+            **kwargs: Additional parameters (unused)
+
+        Returns:
+            List of unverified SearchResult objects ranked by keyword match score
+        """
+        settings = get_settings()
+
+        logger.info(
+            f"Keyword search: query='{query}', user={user_id}, "
+            f"limit={limit}, doc_type={doc_type}"
+        )
+
+        # Tokenize query
+        query_tokens = self._process_query(query)
+        logger.debug(f"Query tokens: {query_tokens}")
+
+        # Build Qdrant filter
+        filter_conditions = [
+            FieldCondition(key="user_id", match=MatchValue(value=user_id))
+        ]
+        if doc_type:
+            filter_conditions.append(
+                FieldCondition(key="doc_type", match=MatchValue(value=doc_type))
+            )
+
+        # Scroll through Qdrant to get all matching documents
+        # We need title and excerpt from payload for token matching
+        qdrant_client = await get_qdrant_client()
+        collection = settings.get_collection_name()
+
+        all_points = []
+        offset = None
+
+        # Scroll through all points matching filter
+        while True:
+            scroll_result, next_offset = await qdrant_client.scroll(
+                collection_name=collection,
+                scroll_filter=Filter(must=filter_conditions),
+                limit=100,  # Batch size
+                offset=offset,
+                with_payload=[
+                    "doc_id",
+                    "doc_type",
+                    "title",
+                    "excerpt",
+                    "chunk_index",
+                    "total_chunks",
+                ],
+                with_vectors=False,  # Don't need vectors for keyword search
+            )
+
+            all_points.extend(scroll_result)
+
+            if next_offset is None:
+                break
+            offset = next_offset
+
+        logger.debug(
+            f"Retrieved {len(all_points)} points from Qdrant for keyword search"
+        )
+
+        # Deduplicate by (doc_id, doc_type) - keep best chunk per document
+        seen_docs = {}
+        for point in all_points:
+            doc_id = int(point.payload["doc_id"])
+            dtype = point.payload.get("doc_type", "note")
+            doc_key = (doc_id, dtype)
+
+            # Keep first chunk (chunk_index=0) as it has the most relevant content
+            chunk_idx = point.payload.get("chunk_index", 0)
+            if doc_key not in seen_docs or chunk_idx == 0:
+                seen_docs[doc_key] = point
+
+        logger.debug(f"Deduplicated to {len(seen_docs)} unique documents")
+
+        # Score each document based on keyword matches
+        scored_results = []
+        for doc_key, point in seen_docs.items():
+            doc_id, dtype = doc_key
+            title = point.payload.get("title", "")
+            excerpt = point.payload.get("excerpt", "")
+
+            # Calculate keyword match score
+            score = self._calculate_score(query_tokens, title, excerpt)
+
+            if score > 0:  # Only include matches
+                scored_results.append(
+                    {
+                        "doc_id": doc_id,
+                        "doc_type": dtype,
+                        "title": title,
+                        "excerpt": excerpt,
+                        "score": score,
+                    }
+                )
+
+        # Sort by score (descending) and limit
+        scored_results.sort(key=lambda x: x["score"], reverse=True)
+        top_results = scored_results[:limit]
+
+        # Return unverified results (verification happens at output stage)
+        final_results = []
+        for result in top_results:
+            final_results.append(
+                SearchResult(
+                    id=result["doc_id"],
+                    doc_type=result["doc_type"],
+                    title=result["title"],
+                    excerpt=result["excerpt"],
+                    score=result["score"],
+                    metadata={},
+                )
+            )
+
+        logger.info(f"Keyword search returned {len(final_results)} unverified results")
+        if final_results:
+            result_details = [
+                f"{r.doc_type}_{r.id} (score={r.score:.3f}, title='{r.title}')"
+                for r in final_results[:5]
+            ]
+            logger.debug(f"Top keyword results: {', '.join(result_details)}")
+
+        return final_results
+
+    def _process_query(self, query: str) -> list[str]:
+        """Tokenize and normalize query.
+
+        Args:
+            query: Raw query string
+
+        Returns:
+            List of normalized tokens
+        """
+        # Convert to lowercase and split into tokens
+        tokens = query.lower().split()
+
+        # Filter out very short tokens (optional)
+        tokens = [token for token in tokens if len(token) > 1]
+
+        return tokens
+
+    def _calculate_score(
+        self, query_tokens: list[str], title: str, content: str
+    ) -> float:
+        """Calculate relevance score based on token matches.
+
+        Args:
+            query_tokens: List of query tokens
+            title: Document title
+            content: Document content
+
+        Returns:
+            Relevance score (0.0-1.0)
+        """
+        if not query_tokens:
+            return 0.0
+
+        # Process title and content
+        title_tokens = title.lower().split()
+        content_tokens = content.lower().split()
+
+        score = 0.0
+
+        # Count matches in title
+        title_matches = sum(1 for qt in query_tokens if qt in title_tokens)
+        if query_tokens:  # Avoid division by zero
+            title_match_ratio = title_matches / len(query_tokens)
+            score += self.TITLE_WEIGHT * title_match_ratio
+
+        # Count matches in content
+        content_matches = sum(1 for qt in query_tokens if qt in content_tokens)
+        if query_tokens:
+            content_match_ratio = content_matches / len(query_tokens)
+            score += self.CONTENT_WEIGHT * content_match_ratio
+
+        # Normalize score to 0-1 range
+        # Max score would be TITLE_WEIGHT + CONTENT_WEIGHT if all tokens match everywhere
+        max_score = self.TITLE_WEIGHT + self.CONTENT_WEIGHT
+        normalized_score = min(score / max_score, 1.0)
+
+        return normalized_score
+
+    def _extract_excerpt(
+        self, content: str, query_tokens: list[str], max_length: int = 200
+    ) -> str:
+        """Extract excerpt showing match context.
+
+        Args:
+            content: Full document content
+            query_tokens: Query tokens to find
+            max_length: Maximum excerpt length in characters
+
+        Returns:
+            Excerpt string with context around matches
+        """
+        if not content:
+            return ""
+
+        content_lower = content.lower()
+
+        # Find first occurrence of any query token
+        first_match_pos = -1
+        for token in query_tokens:
+            pos = content_lower.find(token)
+            if pos != -1:
+                if first_match_pos == -1 or pos < first_match_pos:
+                    first_match_pos = pos
+
+        if first_match_pos == -1:
+            # No matches found, return beginning
+            return content[:max_length].strip() + (
+                "..." if len(content) > max_length else ""
+            )
+
+        # Extract context around match
+        start = max(0, first_match_pos - max_length // 2)
+        end = min(len(content), first_match_pos + max_length // 2)
+
+        excerpt = content[start:end].strip()
+
+        # Add ellipsis if truncated
+        if start > 0:
+            excerpt = "..." + excerpt
+        if end < len(content):
+            excerpt = excerpt + "..."
+
+        return excerpt

nextcloud_mcp_server/search/semantic.py

@@ -0,0 +1,166 @@
+"""Semantic search algorithm using vector similarity (Qdrant)."""
+
+import logging
+from typing import Any
+
+from qdrant_client.models import FieldCondition, Filter, MatchValue
+
+from nextcloud_mcp_server.config import get_settings
+from nextcloud_mcp_server.embedding import get_embedding_service
+from nextcloud_mcp_server.observability.metrics import record_qdrant_operation
+from nextcloud_mcp_server.search.algorithms import SearchAlgorithm, SearchResult
+from nextcloud_mcp_server.vector.qdrant_client import get_qdrant_client
+
+logger = logging.getLogger(__name__)
+
+
+class SemanticSearchAlgorithm(SearchAlgorithm):
+    """Semantic search using vector similarity in Qdrant.
+
+    Searches documents by meaning rather than exact keywords using
+    768-dimensional embeddings and cosine distance.
+    """
+
+    def __init__(self, score_threshold: float = 0.7):
+        """Initialize semantic search algorithm.
+
+        Args:
+            score_threshold: Minimum similarity score (0-1, default: 0.7)
+        """
+        self.score_threshold = score_threshold
+
+    @property
+    def name(self) -> str:
+        return "semantic"
+
+    @property
+    def requires_vector_db(self) -> bool:
+        return True
+
+    async def search(
+        self,
+        query: str,
+        user_id: str,
+        limit: int = 10,
+        doc_type: str | None = None,
+        **kwargs: Any,
+    ) -> list[SearchResult]:
+        """Execute semantic search using vector similarity.
+
+        Returns unverified results from Qdrant. Access verification should be
+        performed separately at the final output stage using verify_search_results().
+
+        Args:
+            query: Natural language search query
+            user_id: User ID for filtering
+            limit: Maximum results to return
+            doc_type: Optional document type filter
+            **kwargs: Additional parameters (score_threshold override)
+
+        Returns:
+            List of unverified SearchResult objects ranked by similarity score
+
+        Raises:
+            McpError: If vector sync is not enabled or search fails
+        """
+        settings = get_settings()
+        score_threshold = kwargs.get("score_threshold", self.score_threshold)
+
+        logger.info(
+            f"Semantic search: query='{query}', user={user_id}, "
+            f"limit={limit}, score_threshold={score_threshold}, doc_type={doc_type}"
+        )
+
+        # 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)})"
+        )
+
+        # Build Qdrant filter
+        filter_conditions = [
+            FieldCondition(
+                key="user_id",
+                match=MatchValue(value=user_id),
+            )
+        ]
+
+        # Add doc_type filter if specified
+        if doc_type:
+            filter_conditions.append(
+                FieldCondition(
+                    key="doc_type",
+                    match=MatchValue(value=doc_type),
+                )
+            )
+
+        # Search Qdrant
+        qdrant_client = await get_qdrant_client()
+        try:
+            search_response = await qdrant_client.query_points(
+                collection_name=settings.get_collection_name(),
+                query=query_embedding,
+                query_filter=Filter(must=filter_conditions),
+                limit=limit * 2,  # Get extra for deduplication
+                score_threshold=score_threshold,
+                with_payload=True,
+                with_vectors=False,  # Don't return vectors to save bandwidth
+            )
+            record_qdrant_operation("search", "success")
+        except Exception:
+            record_qdrant_operation("search", "error")
+            raise
+
+        logger.info(
+            f"Qdrant returned {len(search_response.points)} results "
+            f"(before deduplication)"
+        )
+
+        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 (doc_id, doc_type) - multiple chunks per document
+        seen_docs = set()
+        results = []
+
+        for result in search_response.points:
+            doc_id = int(result.payload["doc_id"])
+            doc_type = result.payload.get("doc_type", "note")
+            doc_key = (doc_id, doc_type)
+
+            # Skip if we've already seen this document
+            if doc_key in seen_docs:
+                continue
+
+            seen_docs.add(doc_key)
+
+            # Return unverified results (verification happens at output stage)
+            results.append(
+                SearchResult(
+                    id=doc_id,
+                    doc_type=doc_type,
+                    title=result.payload.get("title", "Untitled"),
+                    excerpt=result.payload.get("excerpt", ""),
+                    score=result.score,
+                    metadata={
+                        "chunk_index": result.payload.get("chunk_index"),
+                        "total_chunks": result.payload.get("total_chunks"),
+                    },
+                )
+            )
+
+            if len(results) >= limit:
+                break
+
+        logger.info(f"Returning {len(results)} unverified results after deduplication")
+        if results:
+            result_details = [
+                f"{r.doc_type}_{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 results

nextcloud_mcp_server/server/__init__.py

@@ -3,6 +3,7 @@ from .contacts import configure_contacts_tools
 from .cookbook import configure_cookbook_tools
 from .deck import configure_deck_tools
 from .notes import configure_notes_tools
+from .semantic import configure_semantic_tools
 from .sharing import configure_sharing_tools
 from .tables import configure_tables_tools
 from .webdav import configure_webdav_tools
@@ -13,6 +14,7 @@ __all__ = [
     "configure_cookbook_tools",
     "configure_deck_tools",
     "configure_notes_tools",
+    "configure_semantic_tools",
     "configure_sharing_tools",
     "configure_tables_tools",
     "configure_webdav_tools",

nextcloud_mcp_server/server/calendar.py

@@ -12,6 +12,7 @@ from nextcloud_mcp_server.models.calendar import (
     ListTodosResponse,
     Todo,
 )
+from nextcloud_mcp_server.observability.metrics import instrument_tool
 
 logger = logging.getLogger(__name__)
 
@@ -20,6 +21,7 @@ def configure_calendar_tools(mcp: FastMCP):
     # Calendar tools
     @mcp.tool()
     @require_scopes("calendar:read")
+    @instrument_tool
     async def nc_calendar_list_calendars(ctx: Context) -> ListCalendarsResponse:
         """List all available calendars for the user"""
         client = await get_client(ctx)
@@ -30,6 +32,7 @@ def configure_calendar_tools(mcp: FastMCP):
 
     @mcp.tool()
     @require_scopes("calendar:write")
+    @instrument_tool
     async def nc_calendar_create_event(
         calendar_name: str,
         title: str,
@@ -106,6 +109,7 @@ def configure_calendar_tools(mcp: FastMCP):
 
     @mcp.tool()
     @require_scopes("calendar:read")
+    @instrument_tool
     async def nc_calendar_list_events(
         calendar_name: str,
         ctx: Context,
@@ -208,6 +212,7 @@ def configure_calendar_tools(mcp: FastMCP):
 
     @mcp.tool()
     @require_scopes("calendar:read")
+    @instrument_tool
     async def nc_calendar_get_event(
         calendar_name: str,
         event_uid: str,
@@ -220,6 +225,7 @@ def configure_calendar_tools(mcp: FastMCP):
 
     @mcp.tool()
     @require_scopes("calendar:write")
+    @instrument_tool
     async def nc_calendar_update_event(
         calendar_name: str,
         event_uid: str,
@@ -293,6 +299,7 @@ def configure_calendar_tools(mcp: FastMCP):
 
     @mcp.tool()
     @require_scopes("calendar:write")
+    @instrument_tool
     async def nc_calendar_delete_event(
         calendar_name: str,
         event_uid: str,
@@ -304,6 +311,7 @@ def configure_calendar_tools(mcp: FastMCP):
 
     @mcp.tool()
     @require_scopes("calendar:write")
+    @instrument_tool
     async def nc_calendar_create_meeting(
         title: str,
         date: str,
@@ -370,6 +378,7 @@ def configure_calendar_tools(mcp: FastMCP):
 
     @mcp.tool()
     @require_scopes("calendar:read")
+    @instrument_tool
     async def nc_calendar_get_upcoming_events(
         ctx: Context,
         calendar_name: str = "",  # Empty = all calendars
@@ -420,6 +429,7 @@ def configure_calendar_tools(mcp: FastMCP):
 
     @mcp.tool()
     @require_scopes("calendar:read")
+    @instrument_tool
     async def nc_calendar_find_availability(
         duration_minutes: int,
         ctx: Context,
@@ -500,6 +510,7 @@ def configure_calendar_tools(mcp: FastMCP):
 
     @mcp.tool()
     @require_scopes("calendar:write")
+    @instrument_tool
     async def nc_calendar_bulk_operations(
         operation: str,  # "update", "delete", "move"
         ctx: Context,
@@ -749,6 +760,7 @@ def configure_calendar_tools(mcp: FastMCP):
 
     @mcp.tool()
     @require_scopes("calendar:write")
+    @instrument_tool
     async def nc_calendar_manage_calendar(
         action: str,  # "create", "delete", "update", "list"
         ctx: Context,
@@ -818,6 +830,7 @@ def configure_calendar_tools(mcp: FastMCP):
 
     @mcp.tool()
     @require_scopes("todo:read", "calendar:read")
+    @instrument_tool
     async def nc_calendar_list_todos(
         calendar_name: str,
         ctx: Context,
@@ -863,6 +876,7 @@ def configure_calendar_tools(mcp: FastMCP):
 
     @mcp.tool()
     @require_scopes("todo:write", "calendar:read")
+    @instrument_tool
     async def nc_calendar_create_todo(
         calendar_name: str,
         summary: str,
@@ -906,6 +920,7 @@ def configure_calendar_tools(mcp: FastMCP):
 
     @mcp.tool()
     @require_scopes("todo:write", "calendar:read")
+    @instrument_tool
     async def nc_calendar_update_todo(
         calendar_name: str,
         todo_uid: str,
@@ -966,6 +981,7 @@ def configure_calendar_tools(mcp: FastMCP):
 
     @mcp.tool()
     @require_scopes("todo:write", "calendar:read")
+    @instrument_tool
     async def nc_calendar_delete_todo(
         calendar_name: str,
         todo_uid: str,
@@ -986,6 +1002,7 @@ def configure_calendar_tools(mcp: FastMCP):
 
     @mcp.tool()
     @require_scopes("todo:read", "calendar:read")
+    @instrument_tool
     async def nc_calendar_search_todos(
         ctx: Context,
         status: Optional[str] = None,

nextcloud_mcp_server/server/contacts.py

@@ -4,6 +4,7 @@ from mcp.server.fastmcp import Context, FastMCP
 
 from nextcloud_mcp_server.auth import require_scopes
 from nextcloud_mcp_server.context import get_client
+from nextcloud_mcp_server.observability.metrics import instrument_tool
 
 logger = logging.getLogger(__name__)
 
@@ -12,6 +13,7 @@ def configure_contacts_tools(mcp: FastMCP):
     # Contacts tools
     @mcp.tool()
     @require_scopes("contacts:read")
+    @instrument_tool
     async def nc_contacts_list_addressbooks(ctx: Context):
         """List all addressbooks for the user."""
         client = await get_client(ctx)
@@ -19,6 +21,7 @@ def configure_contacts_tools(mcp: FastMCP):
 
     @mcp.tool()
     @require_scopes("contacts:read")
+    @instrument_tool
     async def nc_contacts_list_contacts(ctx: Context, *, addressbook: str):
         """List all contacts in the specified addressbook."""
         client = await get_client(ctx)
@@ -26,6 +29,7 @@ def configure_contacts_tools(mcp: FastMCP):
 
     @mcp.tool()
     @require_scopes("contacts:write")
+    @instrument_tool
     async def nc_contacts_create_addressbook(
         ctx: Context, *, name: str, display_name: str
     ):
@@ -42,6 +46,7 @@ def configure_contacts_tools(mcp: FastMCP):
 
     @mcp.tool()
     @require_scopes("contacts:write")
+    @instrument_tool
     async def nc_contacts_delete_addressbook(ctx: Context, *, name: str):
         """Delete an addressbook."""
         client = await get_client(ctx)
@@ -49,6 +54,7 @@ def configure_contacts_tools(mcp: FastMCP):
 
     @mcp.tool()
     @require_scopes("contacts:write")
+    @instrument_tool
     async def nc_contacts_create_contact(
         ctx: Context, *, addressbook: str, uid: str, contact_data: dict
     ):
@@ -66,6 +72,7 @@ def configure_contacts_tools(mcp: FastMCP):
 
     @mcp.tool()
     @require_scopes("contacts:write")
+    @instrument_tool
     async def nc_contacts_delete_contact(ctx: Context, *, addressbook: str, uid: str):
         """Delete a contact."""
         client = await get_client(ctx)
@@ -73,6 +80,7 @@ def configure_contacts_tools(mcp: FastMCP):
 
     @mcp.tool()
     @require_scopes("contacts:write")
+    @instrument_tool
     async def nc_contacts_update_contact(
         ctx: Context, *, addressbook: str, uid: str, contact_data: dict, etag: str = ""
     ):

nextcloud_mcp_server/server/cookbook.py

@@ -24,6 +24,7 @@ from nextcloud_mcp_server.models.cookbook import (
     UpdateRecipeResponse,
     Version,
 )
+from nextcloud_mcp_server.observability.metrics import instrument_tool
 
 logger = logging.getLogger(__name__)
 
@@ -72,6 +73,7 @@ def configure_cookbook_tools(mcp: FastMCP):
 
     @mcp.tool()
     @require_scopes("cookbook:write")
+    @instrument_tool
     async def nc_cookbook_import_recipe(url: str, ctx: Context) -> ImportRecipeResponse:
         """Import a recipe from a URL using schema.org metadata.
 
@@ -129,6 +131,7 @@ def configure_cookbook_tools(mcp: FastMCP):
 
     @mcp.tool()
     @require_scopes("cookbook:read")
+    @instrument_tool
     async def nc_cookbook_list_recipes(ctx: Context) -> ListRecipesResponse:
         """Get all recipes in the database"""
         client = await get_client(ctx)
@@ -154,6 +157,7 @@ def configure_cookbook_tools(mcp: FastMCP):
 
     @mcp.tool()
     @require_scopes("cookbook:read")
+    @instrument_tool
     async def nc_cookbook_get_recipe(recipe_id: int, ctx: Context) -> Recipe:
         """Get a specific recipe by its ID"""
         client = await get_client(ctx)
@@ -179,6 +183,7 @@ def configure_cookbook_tools(mcp: FastMCP):
 
     @mcp.tool()
     @require_scopes("cookbook:write")
+    @instrument_tool
     async def nc_cookbook_create_recipe(
         name: str,
         description: str | None = None,
@@ -258,6 +263,7 @@ def configure_cookbook_tools(mcp: FastMCP):
 
     @mcp.tool()
     @require_scopes("cookbook:write")
+    @instrument_tool
     async def nc_cookbook_update_recipe(
         recipe_id: int,
         name: str | None = None,
@@ -347,6 +353,7 @@ def configure_cookbook_tools(mcp: FastMCP):
 
     @mcp.tool()
     @require_scopes("cookbook:write")
+    @instrument_tool
     async def nc_cookbook_delete_recipe(
         recipe_id: int, ctx: Context
     ) -> DeleteRecipeResponse:
@@ -382,6 +389,7 @@ def configure_cookbook_tools(mcp: FastMCP):
 
     @mcp.tool()
     @require_scopes("cookbook:read")
+    @instrument_tool
     async def nc_cookbook_search_recipes(
         query: str, ctx: Context
     ) -> SearchRecipesResponse:
@@ -418,6 +426,7 @@ def configure_cookbook_tools(mcp: FastMCP):
 
     @mcp.tool()
     @require_scopes("cookbook:read")
+    @instrument_tool
     async def nc_cookbook_list_categories(ctx: Context) -> ListCategoriesResponse:
         """Get all known categories.
 
@@ -445,6 +454,7 @@ def configure_cookbook_tools(mcp: FastMCP):
 
     @mcp.tool()
     @require_scopes("cookbook:read")
+    @instrument_tool
     async def nc_cookbook_get_recipes_in_category(
         category: str, ctx: Context
     ) -> ListRecipesResponse:
@@ -481,6 +491,7 @@ def configure_cookbook_tools(mcp: FastMCP):
 
     @mcp.tool()
     @require_scopes("cookbook:read")
+    @instrument_tool
     async def nc_cookbook_list_keywords(ctx: Context) -> ListKeywordsResponse:
         """Get all known keywords/tags"""
         client = await get_client(ctx)
@@ -506,6 +517,7 @@ def configure_cookbook_tools(mcp: FastMCP):
 
     @mcp.tool()
     @require_scopes("cookbook:read")
+    @instrument_tool
     async def nc_cookbook_get_recipes_with_keywords(
         keywords: list[str], ctx: Context
     ) -> ListRecipesResponse:
@@ -540,6 +552,7 @@ def configure_cookbook_tools(mcp: FastMCP):
 
     @mcp.tool()
     @require_scopes("cookbook:write")
+    @instrument_tool
     async def nc_cookbook_set_config(
         folder: str | None = None,
         update_interval: int | None = None,
@@ -583,6 +596,7 @@ def configure_cookbook_tools(mcp: FastMCP):
 
     @mcp.tool()
     @require_scopes("cookbook:write")
+    @instrument_tool
     async def nc_cookbook_reindex(ctx: Context) -> ReindexResponse:
         """Trigger a rescan of all recipes into the caching database.
 

nextcloud_mcp_server/server/deck.py

@@ -18,6 +18,7 @@ from nextcloud_mcp_server.models.deck import (
     LabelOperationResponse,
     StackOperationResponse,
 )
+from nextcloud_mcp_server.observability.metrics import instrument_tool
 
 logger = logging.getLogger(__name__)
 
@@ -118,6 +119,7 @@ def configure_deck_tools(mcp: FastMCP):
 
     @mcp.tool()
     @require_scopes("deck:read")
+    @instrument_tool
     async def deck_get_boards(ctx: Context) -> list[DeckBoard]:
         """Get all Nextcloud Deck boards"""
         client = await get_client(ctx)
@@ -126,6 +128,7 @@ def configure_deck_tools(mcp: FastMCP):
 
     @mcp.tool()
     @require_scopes("deck:read")
+    @instrument_tool
     async def deck_get_board(ctx: Context, board_id: int) -> DeckBoard:
         """Get details of a specific Nextcloud Deck board"""
         client = await get_client(ctx)
@@ -134,6 +137,7 @@ def configure_deck_tools(mcp: FastMCP):
 
     @mcp.tool()
     @require_scopes("deck:read")
+    @instrument_tool
     async def deck_get_stacks(ctx: Context, board_id: int) -> list[DeckStack]:
         """Get all stacks in a Nextcloud Deck board"""
         client = await get_client(ctx)
@@ -142,6 +146,7 @@ def configure_deck_tools(mcp: FastMCP):
 
     @mcp.tool()
     @require_scopes("deck:read")
+    @instrument_tool
     async def deck_get_stack(ctx: Context, board_id: int, stack_id: int) -> DeckStack:
         """Get details of a specific Nextcloud Deck stack"""
         client = await get_client(ctx)
@@ -150,6 +155,7 @@ def configure_deck_tools(mcp: FastMCP):
 
     @mcp.tool()
     @require_scopes("deck:read")
+    @instrument_tool
     async def deck_get_cards(
         ctx: Context, board_id: int, stack_id: int
     ) -> list[DeckCard]:
@@ -162,6 +168,7 @@ def configure_deck_tools(mcp: FastMCP):
 
     @mcp.tool()
     @require_scopes("deck:read")
+    @instrument_tool
     async def deck_get_card(
         ctx: Context, board_id: int, stack_id: int, card_id: int
     ) -> DeckCard:
@@ -172,6 +179,7 @@ def configure_deck_tools(mcp: FastMCP):
 
     @mcp.tool()
     @require_scopes("deck:read")
+    @instrument_tool
     async def deck_get_labels(ctx: Context, board_id: int) -> list[DeckLabel]:
         """Get all labels in a Nextcloud Deck board"""
         client = await get_client(ctx)
@@ -180,6 +188,7 @@ def configure_deck_tools(mcp: FastMCP):
 
     @mcp.tool()
     @require_scopes("deck:read")
+    @instrument_tool
     async def deck_get_label(ctx: Context, board_id: int, label_id: int) -> DeckLabel:
         """Get details of a specific Nextcloud Deck label"""
         client = await get_client(ctx)
@@ -190,6 +199,7 @@ def configure_deck_tools(mcp: FastMCP):
 
     @mcp.tool()
     @require_scopes("deck:write")
+    @instrument_tool
     async def deck_create_board(
         ctx: Context, title: str, color: str
     ) -> CreateBoardResponse:
@@ -207,6 +217,7 @@ def configure_deck_tools(mcp: FastMCP):
 
     @mcp.tool()
     @require_scopes("deck:write")
+    @instrument_tool
     async def deck_create_stack(
         ctx: Context, board_id: int, title: str, order: int
     ) -> CreateStackResponse:
@@ -223,6 +234,7 @@ def configure_deck_tools(mcp: FastMCP):
 
     @mcp.tool()
     @require_scopes("deck:write")
+    @instrument_tool
     async def deck_update_stack(
         ctx: Context,
         board_id: int,
@@ -249,6 +261,7 @@ def configure_deck_tools(mcp: FastMCP):
 
     @mcp.tool()
     @require_scopes("deck:write")
+    @instrument_tool
     async def deck_delete_stack(
         ctx: Context, board_id: int, stack_id: int
     ) -> StackOperationResponse:
@@ -270,6 +283,7 @@ def configure_deck_tools(mcp: FastMCP):
     # Card Tools
     @mcp.tool()
     @require_scopes("deck:write")
+    @instrument_tool
     async def deck_create_card(
         ctx: Context,
         board_id: int,
@@ -304,6 +318,7 @@ def configure_deck_tools(mcp: FastMCP):
 
     @mcp.tool()
     @require_scopes("deck:write")
+    @instrument_tool
     async def deck_update_card(
         ctx: Context,
         board_id: int,
@@ -357,6 +372,7 @@ def configure_deck_tools(mcp: FastMCP):
 
     @mcp.tool()
     @require_scopes("deck:write")
+    @instrument_tool
     async def deck_delete_card(
         ctx: Context, board_id: int, stack_id: int, card_id: int
     ) -> CardOperationResponse:
@@ -379,6 +395,7 @@ def configure_deck_tools(mcp: FastMCP):
 
     @mcp.tool()
     @require_scopes("deck:write")
+    @instrument_tool
     async def deck_archive_card(
         ctx: Context, board_id: int, stack_id: int, card_id: int
     ) -> CardOperationResponse:
@@ -401,6 +418,7 @@ def configure_deck_tools(mcp: FastMCP):
 
     @mcp.tool()
     @require_scopes("deck:write")
+    @instrument_tool
     async def deck_unarchive_card(
         ctx: Context, board_id: int, stack_id: int, card_id: int
     ) -> CardOperationResponse:
@@ -423,6 +441,7 @@ def configure_deck_tools(mcp: FastMCP):
 
     @mcp.tool()
     @require_scopes("deck:write")
+    @instrument_tool
     async def deck_reorder_card(
         ctx: Context,
         board_id: int,
@@ -455,6 +474,7 @@ def configure_deck_tools(mcp: FastMCP):
     # Label Tools
     @mcp.tool()
     @require_scopes("deck:write")
+    @instrument_tool
     async def deck_create_label(
         ctx: Context, board_id: int, title: str, color: str
     ) -> CreateLabelResponse:
@@ -471,6 +491,7 @@ def configure_deck_tools(mcp: FastMCP):
 
     @mcp.tool()
     @require_scopes("deck:write")
+    @instrument_tool
     async def deck_update_label(
         ctx: Context,
         board_id: int,
@@ -497,6 +518,7 @@ def configure_deck_tools(mcp: FastMCP):
 
     @mcp.tool()
     @require_scopes("deck:write")
+    @instrument_tool
     async def deck_delete_label(
         ctx: Context, board_id: int, label_id: int
     ) -> LabelOperationResponse:
@@ -518,6 +540,7 @@ def configure_deck_tools(mcp: FastMCP):
     # Card-Label Assignment Tools
     @mcp.tool()
     @require_scopes("deck:write")
+    @instrument_tool
     async def deck_assign_label_to_card(
         ctx: Context, board_id: int, stack_id: int, card_id: int, label_id: int
     ) -> CardOperationResponse:
@@ -541,6 +564,7 @@ def configure_deck_tools(mcp: FastMCP):
 
     @mcp.tool()
     @require_scopes("deck:write")
+    @instrument_tool
     async def deck_remove_label_from_card(
         ctx: Context, board_id: int, stack_id: int, card_id: int, label_id: int
     ) -> CardOperationResponse:
@@ -565,6 +589,7 @@ def configure_deck_tools(mcp: FastMCP):
     # Card-User Assignment Tools
     @mcp.tool()
     @require_scopes("deck:write")
+    @instrument_tool
     async def deck_assign_user_to_card(
         ctx: Context, board_id: int, stack_id: int, card_id: int, user_id: str
     ) -> CardOperationResponse:
@@ -588,6 +613,7 @@ def configure_deck_tools(mcp: FastMCP):
 
     @mcp.tool()
     @require_scopes("deck:write")
+    @instrument_tool
     async def deck_unassign_user_from_card(
         ctx: Context, board_id: int, stack_id: int, card_id: int, user_id: str
     ) -> CardOperationResponse:

nextcloud_mcp_server/server/notes.py

@@ -17,6 +17,7 @@ from nextcloud_mcp_server.models.notes import (
     SearchNotesResponse,
     UpdateNoteResponse,
 )
+from nextcloud_mcp_server.observability.metrics import instrument_tool
 
 logger = logging.getLogger(__name__)
 
@@ -86,6 +87,7 @@ def configure_notes_tools(mcp: FastMCP):
 
     @mcp.tool()
     @require_scopes("notes:write")
+    @instrument_tool
     async def nc_notes_create_note(
         title: str, content: str, category: str, ctx: Context
     ) -> CreateNoteResponse:
@@ -132,6 +134,7 @@ def configure_notes_tools(mcp: FastMCP):
 
     @mcp.tool()
     @require_scopes("notes:write")
+    @instrument_tool
     async def nc_notes_update_note(
         note_id: int,
         etag: str,
@@ -197,6 +200,7 @@ def configure_notes_tools(mcp: FastMCP):
 
     @mcp.tool()
     @require_scopes("notes:write")
+    @instrument_tool
     async def nc_notes_append_content(
         note_id: int, content: str, ctx: Context
     ) -> AppendContentResponse:
@@ -247,6 +251,7 @@ def configure_notes_tools(mcp: FastMCP):
 
     @mcp.tool()
     @require_scopes("notes:read")
+    @instrument_tool
     async def nc_notes_search_notes(query: str, ctx: Context) -> SearchNotesResponse:
         """Search notes by title or content, returning only id, title, and category (requires notes:read scope)."""
         client = await get_client(ctx)
@@ -293,6 +298,7 @@ def configure_notes_tools(mcp: FastMCP):
 
     @mcp.tool()
     @require_scopes("notes:read")
+    @instrument_tool
     async def nc_notes_get_note(note_id: int, ctx: Context) -> Note:
         """Get a specific note by its ID (requires notes:read scope)"""
         client = await get_client(ctx)
@@ -322,6 +328,7 @@ def configure_notes_tools(mcp: FastMCP):
 
     @mcp.tool()
     @require_scopes("notes:read")
+    @instrument_tool
     async def nc_notes_get_attachment(
         note_id: int, attachment_filename: str, ctx: Context
     ) -> dict[str, str]:
@@ -368,6 +375,7 @@ def configure_notes_tools(mcp: FastMCP):
 
     @mcp.tool()
     @require_scopes("notes:write")
+    @instrument_tool
     async def nc_notes_delete_note(note_id: int, ctx: Context) -> DeleteNoteResponse:
         """Delete a note permanently"""
         logger.info("Deleting note %s", note_id)

nextcloud_mcp_server/server/oauth_tools.py

@@ -18,7 +18,7 @@ from mcp.server.fastmcp import Context
 from pydantic import BaseModel, Field
 
 from nextcloud_mcp_server.auth import require_scopes
-from nextcloud_mcp_server.auth.refresh_token_storage import RefreshTokenStorage
+from nextcloud_mcp_server.auth.storage import RefreshTokenStorage
 from nextcloud_mcp_server.auth.token_broker import TokenBrokerService
 from nextcloud_mcp_server.auth.userinfo_routes import _query_idp_userinfo
 

nextcloud_mcp_server/server/semantic.py

@@ -0,0 +1,654 @@
+"""Semantic search MCP tools using vector database."""
+
+import logging
+from typing import Literal
+
+import anyio
+from httpx import RequestError
+from mcp.server.fastmcp import Context, FastMCP
+from mcp.shared.exceptions import McpError
+from mcp.types import (
+    ErrorData,
+    ModelHint,
+    ModelPreferences,
+    SamplingMessage,
+    TextContent,
+)
+
+from nextcloud_mcp_server.auth import require_scopes
+from nextcloud_mcp_server.context import get_client
+from nextcloud_mcp_server.models.semantic import (
+    SamplingSearchResponse,
+    SemanticSearchResponse,
+    SemanticSearchResult,
+    VectorSyncStatusResponse,
+)
+from nextcloud_mcp_server.observability.metrics import (
+    instrument_tool,
+)
+from nextcloud_mcp_server.search import (
+    FuzzySearchAlgorithm,
+    HybridSearchAlgorithm,
+    KeywordSearchAlgorithm,
+    SemanticSearchAlgorithm,
+)
+
+logger = logging.getLogger(__name__)
+
+
+def configure_semantic_tools(mcp: FastMCP):
+    """Configure semantic search tools for MCP server."""
+
+    @mcp.tool()
+    @require_scopes("semantic:read")
+    @instrument_tool
+    async def nc_semantic_search(
+        query: str,
+        ctx: Context,
+        limit: int = 10,
+        doc_types: list[str] | None = None,
+        score_threshold: float = 0.7,
+        algorithm: Literal["semantic", "keyword", "fuzzy", "hybrid"] = "hybrid",
+        semantic_weight: float = 0.5,
+        keyword_weight: float = 0.3,
+        fuzzy_weight: float = 0.2,
+    ) -> SemanticSearchResponse:
+        """
+        Search Nextcloud content using configurable algorithms with cross-app support.
+
+        Supports multiple search algorithms with client-configurable weighting:
+        - semantic: Vector similarity search (requires VECTOR_SYNC_ENABLED=true)
+        - keyword: Token-based matching (title matches weighted 3x)
+        - fuzzy: Character overlap matching (typo-tolerant)
+        - hybrid: Combines all algorithms using Reciprocal Rank Fusion (default)
+
+        Document types are queried from the vector database to determine what's
+        actually indexed. Currently only "note" documents are fully supported.
+
+        Args:
+            query: Natural language search query
+            limit: Maximum number of results to return (default: 10)
+            doc_types: Document types to search (e.g., ["note", "file"]). None = search all indexed types (default)
+            score_threshold: Minimum similarity score for semantic/hybrid (0-1, default: 0.7)
+            algorithm: Search algorithm to use (default: "hybrid")
+            semantic_weight: Weight for semantic results in hybrid mode (default: 0.5)
+            keyword_weight: Weight for keyword results in hybrid mode (default: 0.3)
+            fuzzy_weight: Weight for fuzzy results in hybrid mode (default: 0.2)
+
+        Returns:
+            SemanticSearchResponse with matching documents and relevance scores
+        """
+        from nextcloud_mcp_server.config import get_settings
+
+        settings = get_settings()
+        client = await get_client(ctx)
+        username = client.username
+
+        logger.info(
+            f"Search: query='{query}', user={username}, algorithm={algorithm}, "
+            f"limit={limit}, score_threshold={score_threshold}"
+        )
+
+        try:
+            # Create appropriate algorithm instance
+            if algorithm == "semantic":
+                if not settings.vector_sync_enabled:
+                    raise McpError(
+                        ErrorData(
+                            code=-1,
+                            message="Semantic search requires VECTOR_SYNC_ENABLED=true",
+                        )
+                    )
+                search_algo = SemanticSearchAlgorithm(score_threshold=score_threshold)
+            elif algorithm == "keyword":
+                search_algo = KeywordSearchAlgorithm()
+            elif algorithm == "fuzzy":
+                search_algo = FuzzySearchAlgorithm()
+            elif algorithm == "hybrid":
+                if semantic_weight > 0 and not settings.vector_sync_enabled:
+                    raise McpError(
+                        ErrorData(
+                            code=-1,
+                            message="Hybrid search with semantic component requires VECTOR_SYNC_ENABLED=true",
+                        )
+                    )
+                search_algo = HybridSearchAlgorithm(
+                    semantic_weight=semantic_weight,
+                    keyword_weight=keyword_weight,
+                    fuzzy_weight=fuzzy_weight,
+                )
+            else:
+                raise McpError(
+                    ErrorData(code=-1, message=f"Unknown algorithm: {algorithm}")
+                )
+
+            # Execute search across requested document types
+            # If doc_types is None, search all indexed types (cross-app search)
+            # If doc_types is a list, search only those types
+            all_results = []
+
+            if doc_types is None:
+                # Cross-app search: search all indexed types
+                # Get unverified results from Qdrant
+                unverified_results = await search_algo.search(
+                    query=query,
+                    user_id=username,
+                    limit=limit * 2,  # Get extra for access filtering
+                    doc_type=None,  # Signal to search all types
+                    score_threshold=score_threshold,
+                )
+                all_results.extend(unverified_results)
+            else:
+                # Search specific document types
+                # For each requested type, execute search and combine results
+                for dtype in doc_types:
+                    unverified_results = await search_algo.search(
+                        query=query,
+                        user_id=username,
+                        limit=limit * 2,  # Get extra for combining and filtering
+                        doc_type=dtype,
+                        score_threshold=score_threshold,
+                    )
+                    all_results.extend(unverified_results)
+
+                # Sort combined results by score
+                all_results.sort(key=lambda r: r.score, reverse=True)
+
+            # Deduplicate results (hybrid search may return same doc from dense + sparse)
+            # Qdrant already filters by user_id for multi-tenant isolation
+            # Sampling tool will verify access when fetching full content
+            seen = set()
+            unique_results = []
+            for result in all_results:
+                key = (result.id, result.doc_type)
+                if key not in seen:
+                    seen.add(key)
+                    unique_results.append(result)
+
+            search_results = unique_results[:limit]  # Final limit after deduplication
+
+            # Convert SearchResult objects to SemanticSearchResult for response
+            results = []
+            for r in search_results:
+                results.append(
+                    SemanticSearchResult(
+                        id=r.id,
+                        doc_type=r.doc_type,
+                        title=r.title,
+                        category=r.metadata.get("category", "") if r.metadata else "",
+                        excerpt=r.excerpt,
+                        score=r.score,
+                        chunk_index=r.metadata.get("chunk_index", 0)
+                        if r.metadata
+                        else 0,
+                        total_chunks=r.metadata.get("total_chunks", 1)
+                        if r.metadata
+                        else 1,
+                    )
+                )
+
+            logger.info(f"Returning {len(results)} results from {algorithm} search")
+
+            return SemanticSearchResponse(
+                results=results,
+                query=query,
+                total_found=len(results),
+                search_method=algorithm,
+            )
+
+        except ValueError as e:
+            error_msg = str(e)
+            if "No embedding provider configured" in error_msg:
+                raise McpError(
+                    ErrorData(
+                        code=-1,
+                        message="Embedding service not configured. Set OLLAMA_BASE_URL environment variable.",
+                    )
+                )
+            raise McpError(
+                ErrorData(code=-1, message=f"Configuration error: {error_msg}")
+            )
+        except RequestError as e:
+            raise McpError(
+                ErrorData(code=-1, message=f"Network error during search: {str(e)}")
+            )
+        except Exception as e:
+            logger.error(f"Search error: {e}", exc_info=True)
+            raise McpError(ErrorData(code=-1, message=f"Search failed: {str(e)}"))
+
+    @mcp.tool()
+    @require_scopes("semantic:read")
+    @instrument_tool
+    async def nc_semantic_search_answer(
+        query: str,
+        ctx: Context,
+        limit: int = 5,
+        score_threshold: float = 0.7,
+        max_answer_tokens: int = 500,
+    ) -> SamplingSearchResponse:
+        """
+        Semantic search with LLM-generated answer using MCP sampling.
+
+        Retrieves relevant documents from indexed Nextcloud apps (notes, calendar, deck,
+        files, contacts) using vector similarity search, then uses MCP sampling to request
+        the client's LLM to generate a natural language answer based on the retrieved context.
+
+        This tool combines the power of semantic search (finding relevant content across
+        all your Nextcloud apps) with LLM generation (synthesizing that content into
+        coherent answers). The generated answer includes citations to specific documents
+        with their types, allowing users to verify claims and explore sources.
+
+        The LLM generation happens client-side via MCP sampling. The MCP client
+        controls which model is used, who pays for it, and whether to prompt the
+        user for approval. This keeps the server simple (no LLM API keys needed)
+        while giving users full control over their LLM interactions.
+
+        Args:
+            query: Natural language question to answer (e.g., "What are my Q1 objectives?" or "When is my next dentist appointment?")
+            ctx: MCP context for session access
+            limit: Maximum number of documents to retrieve (default: 5)
+            score_threshold: Minimum similarity score 0-1 (default: 0.7)
+            max_answer_tokens: Maximum tokens for generated answer (default: 500)
+
+        Returns:
+            SamplingSearchResponse containing:
+            - generated_answer: Natural language answer with citations
+            - sources: List of documents with excerpts and relevance scores
+            - model_used: Which model generated the answer
+            - stop_reason: Why generation stopped
+
+        Note: Requires MCP client to support sampling. If sampling is unavailable,
+        the tool gracefully degrades to returning documents with an explanation.
+        The client may prompt the user to approve the sampling request.
+
+        Examples:
+            >>> # Query about objectives across multiple apps
+            >>> result = await nc_semantic_search_answer(
+            ...     query="What are my Q1 2025 project goals?",
+            ...     ctx=ctx
+            ... )
+            >>> print(result.generated_answer)
+            "Based on Document 1 (note: Project Kickoff), Document 2 (calendar event:
+            Q1 Planning Meeting), and Document 3 (deck card: Implement semantic search),
+            your main goals are: 1) Improve semantic search accuracy by 20%,
+            2) Deploy new embedding model, 3) Reduce indexing latency..."
+
+            >>> # Query about appointments
+            >>> result = await nc_semantic_search_answer(
+            ...     query="When is my next dentist appointment?",
+            ...     ctx=ctx,
+            ...     limit=10
+            ... )
+            >>> len(result.sources)  # Calendar events and related notes
+            3
+        """
+        # 1. Retrieve relevant documents via existing semantic search
+        search_response = await nc_semantic_search(
+            query=query,
+            ctx=ctx,
+            limit=limit,
+            score_threshold=score_threshold,
+        )
+
+        # 2. Handle no results case - don't waste a sampling call
+        if not search_response.results:
+            logger.debug(f"No documents found for query: {query}")
+            return SamplingSearchResponse(
+                query=query,
+                generated_answer="No relevant documents found in your Nextcloud content for this query.",
+                sources=[],
+                total_found=0,
+                search_method="semantic_sampling",
+                success=True,
+            )
+
+        # 3. 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. Fetch full content for notes in parallel (also verifies access)
+        # Use anyio task group for concurrent fetching with semaphore to prevent
+        # connection pool exhaustion
+        client = await get_client(ctx)
+        accessible_results = [None] * len(search_response.results)
+        full_contents = [None] * len(search_response.results)
+
+        # Limit concurrent requests to prevent connection pool exhaustion
+        max_concurrent = 20
+        semaphore = anyio.Semaphore(max_concurrent)
+
+        async def fetch_content(index: int, result: SemanticSearchResult):
+            """Fetch full content for a single document (parallel with semaphore)."""
+            async with semaphore:
+                if result.doc_type == "note":
+                    try:
+                        note = await client.notes.get_note(result.id)
+                        # Note is accessible, store result and full content
+                        content = note.get("content", "")
+                        accessible_results[index] = result
+                        full_contents[index] = content
+                        logger.debug(
+                            f"Fetched full content for note {result.id} "
+                            f"(length: {len(content)} chars)"
+                        )
+                    except Exception as e:
+                        # Note might have been deleted or permissions changed
+                        # Leave as None to filter out later
+                        logger.debug(
+                            f"Note {result.id} not accessible: {e}. "
+                            f"Excluding from results."
+                        )
+                else:
+                    # Non-note document types (future: calendar, deck, files)
+                    # For now, keep them with excerpts
+                    accessible_results[index] = result
+                    # full_contents[index] remains None (will use excerpt)
+
+        # Run all fetches in parallel using anyio task group
+        async with anyio.create_task_group() as tg:
+            for idx, result in enumerate(search_response.results):
+                tg.start_soon(fetch_content, idx, result)
+
+        # Filter out None (inaccessible notes) while preserving order
+        final_pairs = [
+            (r, c) for r, c in zip(accessible_results, full_contents) if r is not None
+        ]
+        accessible_results = [r for r, c in final_pairs]
+        full_contents = [c for r, c in final_pairs]
+
+        # Check if we filtered out all results
+        if not accessible_results:
+            logger.warning(f"All search results became inaccessible for query: {query}")
+            return SamplingSearchResponse(
+                query=query,
+                generated_answer="All matching documents are no longer accessible.",
+                sources=[],
+                total_found=0,
+                search_method="semantic_sampling",
+                success=True,
+            )
+
+        # 5. Construct context from accessible documents with full content
+        context_parts = []
+        for idx, (result, content) in enumerate(
+            zip(accessible_results, full_contents), 1
+        ):
+            # Use full content if available (notes), otherwise use excerpt
+            if content is not None:
+                content_field = f"Content: {content}"
+            else:
+                content_field = f"Excerpt: {result.excerpt}"
+
+            context_parts.append(
+                f"[Document {idx}]\n"
+                f"Type: {result.doc_type}\n"
+                f"Title: {result.title}\n"
+                f"Category: {result.category}\n"
+                f"{content_field}\n"
+                f"Relevance Score: {result.score:.2f}\n"
+            )
+
+        context = "\n".join(context_parts)
+
+        # 6. Construct prompt - reuse user's query, add context and instructions
+        prompt = (
+            f"{query}\n\n"
+            f"Here are relevant documents from Nextcloud (notes, calendar events, deck cards, files, contacts):\n\n"
+            f"{context}\n\n"
+            f"Based on the documents above, please provide a comprehensive answer. "
+            f"Cite the document numbers when referencing specific information."
+        )
+
+        logger.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}"
+        )
+
+        # 6. Request LLM completion via MCP sampling with timeout
+
+        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",
+                )
+
+            # 7. Extract answer from sampling response
+            if sampling_result.content.type == "text":
+                generated_answer = sampling_result.content.text
+            else:
+                # Handle non-text responses (shouldn't happen for text prompts)
+                generated_answer = f"Received non-text response of type: {sampling_result.content.type}"
+                logger.warning(
+                    f"Unexpected content type from sampling: {sampling_result.content.type}"
+                )
+
+            logger.info(
+                f"Sampling successful: model={sampling_result.model}, "
+                f"stop_reason={sampling_result.stopReason}, "
+                f"answer_length={len(generated_answer)}"
+            )
+
+            return SamplingSearchResponse(
+                query=query,
+                generated_answer=generated_answer,
+                sources=accessible_results,
+                total_found=len(accessible_results),
+                search_method="semantic_sampling",
+                model_used=sampling_result.model,
+                stop_reason=sampling_result.stopReason,
+                success=True,
+            )
+
+        except TimeoutError:
+            logger.warning(
+                f"Sampling request timed out after 30 seconds for query: '{query}', "
+                f"returning search results only"
+            )
+            return SamplingSearchResponse(
+                query=query,
+                generated_answer=(
+                    f"[Sampling request timed out]\n\n"
+                    f"The answer generation took too long (>30s). "
+                    f"Found {len(accessible_results)} relevant documents. "
+                    f"Please review the sources below or try a simpler query."
+                ),
+                sources=accessible_results,
+                total_found=len(accessible_results),
+                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"Found {len(accessible_results)} relevant documents. "
+                    f"Please review the sources below."
+                ),
+                sources=accessible_results,
+                total_found=len(accessible_results),
+                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 {len(accessible_results)} relevant documents. "
+                    f"Please review the sources below."
+                ),
+                sources=accessible_results,
+                total_found=len(accessible_results),
+                search_method="semantic_sampling_error",
+                success=True,
+            )
+
+    @mcp.tool()
+    @require_scopes("semantic:read")
+    @instrument_tool
+    async def nc_get_vector_sync_status(ctx: Context) -> VectorSyncStatusResponse:
+        """Get the current vector sync status.
+
+        Returns information about the vector sync process, including:
+        - Number of documents indexed in the vector database
+        - Number of documents pending processing
+        - Current sync status (idle, syncing, or disabled)
+
+        This is useful for determining when vector indexing is complete
+        after creating or updating content across all indexed apps.
+        """
+        import os
+
+        # Check if vector sync is enabled
+        vector_sync_enabled = (
+            os.getenv("VECTOR_SYNC_ENABLED", "false").lower() == "true"
+        )
+
+        if not vector_sync_enabled:
+            return VectorSyncStatusResponse(
+                indexed_count=0,
+                pending_count=0,
+                status="disabled",
+                enabled=False,
+            )
+
+        try:
+            # Get document receive stream from lifespan context
+            lifespan_ctx = ctx.request_context.lifespan_context
+            document_receive_stream = getattr(
+                lifespan_ctx, "document_receive_stream", None
+            )
+
+            if document_receive_stream is None:
+                logger.debug(
+                    "document_receive_stream not available in lifespan context"
+                )
+                return VectorSyncStatusResponse(
+                    indexed_count=0,
+                    pending_count=0,
+                    status="unknown",
+                    enabled=True,
+                )
+
+            # Get pending count from stream statistics
+            stream_stats = document_receive_stream.statistics()
+            pending_count = stream_stats.current_buffer_used
+
+            # Get Qdrant client and query indexed count
+            indexed_count = 0
+            try:
+                from nextcloud_mcp_server.config import get_settings
+                from nextcloud_mcp_server.vector.qdrant_client import get_qdrant_client
+
+                settings = get_settings()
+                qdrant_client = await get_qdrant_client()
+
+                # Count documents in collection
+                count_result = await qdrant_client.count(
+                    collection_name=settings.get_collection_name()
+                )
+                indexed_count = count_result.count
+
+            except Exception as e:
+                logger.warning(f"Failed to query Qdrant for indexed count: {e}")
+                # Continue with indexed_count = 0
+
+            # Determine status
+            status = "syncing" if pending_count > 0 else "idle"
+
+            return VectorSyncStatusResponse(
+                indexed_count=indexed_count,
+                pending_count=pending_count,
+                status=status,
+                enabled=True,
+            )
+
+        except Exception as e:
+            logger.error(f"Error getting vector sync status: {e}")
+            raise McpError(
+                ErrorData(
+                    code=-1,
+                    message=f"Failed to retrieve vector sync status: {str(e)}",
+                )
+            )

nextcloud_mcp_server/server/sharing.py

@@ -6,6 +6,7 @@ from mcp.server.fastmcp import Context, FastMCP
 
 from nextcloud_mcp_server.auth import require_scopes
 from nextcloud_mcp_server.context import get_client
+from nextcloud_mcp_server.observability.metrics import instrument_tool
 
 
 def configure_sharing_tools(mcp: FastMCP):
@@ -17,6 +18,7 @@ def configure_sharing_tools(mcp: FastMCP):
 
     @mcp.tool()
     @require_scopes("sharing:write")
+    @instrument_tool
     async def nc_share_create(
         path: str,
         share_with: str,
@@ -56,6 +58,7 @@ def configure_sharing_tools(mcp: FastMCP):
 
     @mcp.tool()
     @require_scopes("sharing:write")
+    @instrument_tool
     async def nc_share_delete(share_id: int, ctx: Context) -> str:
         """Delete a share by its ID.
 
@@ -75,6 +78,7 @@ def configure_sharing_tools(mcp: FastMCP):
 
     @mcp.tool()
     @require_scopes("sharing:write")
+    @instrument_tool
     async def nc_share_get(share_id: int, ctx: Context) -> str:
         """Get information about a specific share.
 
@@ -93,6 +97,7 @@ def configure_sharing_tools(mcp: FastMCP):
 
     @mcp.tool()
     @require_scopes("sharing:write")
+    @instrument_tool
     async def nc_share_list(
         ctx: Context, path: str | None = None, shared_with_me: bool = False
     ) -> str:
@@ -114,6 +119,7 @@ def configure_sharing_tools(mcp: FastMCP):
 
     @mcp.tool()
     @require_scopes("sharing:write")
+    @instrument_tool
     async def nc_share_update(share_id: int, permissions: int, ctx: Context) -> str:
         """Update the permissions of an existing share.
 

nextcloud_mcp_server/server/tables.py

@@ -4,6 +4,7 @@ from mcp.server.fastmcp import Context, FastMCP
 
 from nextcloud_mcp_server.auth import require_scopes
 from nextcloud_mcp_server.context import get_client
+from nextcloud_mcp_server.observability.metrics import instrument_tool
 
 logger = logging.getLogger(__name__)
 
@@ -12,6 +13,7 @@ def configure_tables_tools(mcp: FastMCP):
     # Tables tools
     @mcp.tool()
     @require_scopes("tables:read")
+    @instrument_tool
     async def nc_tables_list_tables(ctx: Context):
         """List all tables available to the user"""
         client = await get_client(ctx)
@@ -19,6 +21,7 @@ def configure_tables_tools(mcp: FastMCP):
 
     @mcp.tool()
     @require_scopes("tables:read")
+    @instrument_tool
     async def nc_tables_get_schema(table_id: int, ctx: Context):
         """Get the schema/structure of a specific table including columns and views"""
         client = await get_client(ctx)
@@ -26,6 +29,7 @@ def configure_tables_tools(mcp: FastMCP):
 
     @mcp.tool()
     @require_scopes("tables:read")
+    @instrument_tool
     async def nc_tables_read_table(
         table_id: int,
         ctx: Context,
@@ -38,6 +42,7 @@ def configure_tables_tools(mcp: FastMCP):
 
     @mcp.tool()
     @require_scopes("tables:write")
+    @instrument_tool
     async def nc_tables_insert_row(table_id: int, data: dict, ctx: Context):
         """Insert a new row into a table.
 
@@ -48,6 +53,7 @@ def configure_tables_tools(mcp: FastMCP):
 
     @mcp.tool()
     @require_scopes("tables:write")
+    @instrument_tool
     async def nc_tables_update_row(row_id: int, data: dict, ctx: Context):
         """Update an existing row in a table.
 
@@ -58,6 +64,7 @@ def configure_tables_tools(mcp: FastMCP):
 
     @mcp.tool()
     @require_scopes("tables:write")
+    @instrument_tool
     async def nc_tables_delete_row(row_id: int, ctx: Context):
         """Delete a row from a table"""
         client = await get_client(ctx)

nextcloud_mcp_server/server/webdav.py

@@ -5,6 +5,7 @@ from mcp.server.fastmcp import Context, FastMCP
 from nextcloud_mcp_server.auth import require_scopes
 from nextcloud_mcp_server.context import get_client
 from nextcloud_mcp_server.models import DirectoryListing, FileInfo, SearchFilesResponse
+from nextcloud_mcp_server.observability.metrics import instrument_tool
 from nextcloud_mcp_server.utils.document_parser import (
     is_parseable_document,
     parse_document,
@@ -17,6 +18,7 @@ def configure_webdav_tools(mcp: FastMCP):
     # WebDAV file system tools
     @mcp.tool()
     @require_scopes("files:read")
+    @instrument_tool
     async def nc_webdav_list_directory(
         ctx: Context, path: str = ""
     ) -> DirectoryListing:
@@ -50,6 +52,7 @@ def configure_webdav_tools(mcp: FastMCP):
 
     @mcp.tool()
     @require_scopes("files:read")
+    @instrument_tool
     async def nc_webdav_read_file(path: str, ctx: Context):
         """Read the content of a file from NextCloud.
 
@@ -130,6 +133,7 @@ def configure_webdav_tools(mcp: FastMCP):
 
     @mcp.tool()
     @require_scopes("files:write")
+    @instrument_tool
     async def nc_webdav_write_file(
         path: str, content: str, ctx: Context, content_type: str | None = None
     ):
@@ -158,6 +162,7 @@ def configure_webdav_tools(mcp: FastMCP):
 
     @mcp.tool()
     @require_scopes("files:write")
+    @instrument_tool
     async def nc_webdav_create_directory(path: str, ctx: Context):
         """Create a directory in NextCloud.
 
@@ -172,6 +177,7 @@ def configure_webdav_tools(mcp: FastMCP):
 
     @mcp.tool()
     @require_scopes("files:write")
+    @instrument_tool
     async def nc_webdav_delete_resource(path: str, ctx: Context):
         """Delete a file or directory in NextCloud.
 
@@ -186,6 +192,7 @@ def configure_webdav_tools(mcp: FastMCP):
 
     @mcp.tool()
     @require_scopes("files:write")
+    @instrument_tool
     async def nc_webdav_move_resource(
         source_path: str, destination_path: str, ctx: Context, overwrite: bool = False
     ):
@@ -206,6 +213,7 @@ def configure_webdav_tools(mcp: FastMCP):
 
     @mcp.tool()
     @require_scopes("files:write")
+    @instrument_tool
     async def nc_webdav_copy_resource(
         source_path: str, destination_path: str, ctx: Context, overwrite: bool = False
     ):
@@ -226,6 +234,7 @@ def configure_webdav_tools(mcp: FastMCP):
 
     @mcp.tool()
     @require_scopes("files:read")
+    @instrument_tool
     async def nc_webdav_search_files(
         ctx: Context,
         scope: str = "",
@@ -342,6 +351,7 @@ def configure_webdav_tools(mcp: FastMCP):
 
     @mcp.tool()
     @require_scopes("files:read")
+    @instrument_tool
     async def nc_webdav_find_by_name(
         pattern: str, ctx: Context, scope: str = "", limit: int | None = None
     ) -> SearchFilesResponse:
@@ -369,6 +379,7 @@ def configure_webdav_tools(mcp: FastMCP):
 
     @mcp.tool()
     @require_scopes("files:read")
+    @instrument_tool
     async def nc_webdav_find_by_type(
         mime_type: str, ctx: Context, scope: str = "", limit: int | None = None
     ) -> SearchFilesResponse:
@@ -396,6 +407,7 @@ def configure_webdav_tools(mcp: FastMCP):
 
     @mcp.tool()
     @require_scopes("files:read")
+    @instrument_tool
     async def nc_webdav_list_favorites(
         ctx: Context, scope: str = "", limit: int | None = None
     ) -> SearchFilesResponse:

nextcloud_mcp_server/server/webhook_presets.py

@@ -0,0 +1,197 @@
+"""Webhook preset configurations for common sync scenarios.
+
+This module defines pre-configured webhook bundles that simplify
+webhook setup for common use cases like Notes sync, Calendar sync, etc.
+"""
+
+from typing import Any, Dict, List, TypedDict
+
+
+class WebhookEventConfig(TypedDict):
+    """Configuration for a single webhook event."""
+
+    event: str  # Fully qualified event class name
+    filter: Dict[str, Any]  # Event filter (optional)
+
+
+class WebhookPreset(TypedDict):
+    """Definition of a webhook preset."""
+
+    name: str  # Display name
+    description: str  # User-friendly description
+    events: List[WebhookEventConfig]  # List of events to register
+    app: str  # Nextcloud app this preset is for
+
+
+# File/Notes webhook events
+FILE_EVENT_CREATED = "OCP\\Files\\Events\\Node\\NodeCreatedEvent"
+FILE_EVENT_WRITTEN = "OCP\\Files\\Events\\Node\\NodeWrittenEvent"
+# Use BeforeNodeDeletedEvent instead of NodeDeletedEvent to get node.id
+# See: https://github.com/nextcloud/server/issues/56371
+FILE_EVENT_DELETED = "OCP\\Files\\Events\\Node\\BeforeNodeDeletedEvent"
+
+# Calendar webhook events
+CALENDAR_EVENT_CREATED = "OCP\\Calendar\\Events\\CalendarObjectCreatedEvent"
+CALENDAR_EVENT_UPDATED = "OCP\\Calendar\\Events\\CalendarObjectUpdatedEvent"
+CALENDAR_EVENT_DELETED = "OCP\\Calendar\\Events\\CalendarObjectDeletedEvent"
+
+# Tables webhook events (Nextcloud 30+)
+TABLES_EVENT_ROW_ADDED = "OCA\\Tables\\Event\\RowAddedEvent"
+TABLES_EVENT_ROW_UPDATED = "OCA\\Tables\\Event\\RowUpdatedEvent"
+TABLES_EVENT_ROW_DELETED = "OCA\\Tables\\Event\\RowDeletedEvent"
+
+# Forms webhook events (Nextcloud 30+)
+FORMS_EVENT_FORM_SUBMITTED = "OCA\\Forms\\Events\\FormSubmittedEvent"
+
+# NOTE: Deck and Contacts do NOT support webhooks
+# Their event classes do not implement IWebhookCompatibleEvent interface.
+# Alternative sync strategies:
+# - Deck: Use polling with ETag-based change detection
+# - Contacts: Use CardDAV sync-token mechanism for efficient syncing
+
+
+WEBHOOK_PRESETS: Dict[str, WebhookPreset] = {
+    "notes_sync": {
+        "name": "Notes Sync",
+        "description": "Real-time synchronization for Notes app (create, update, delete)",
+        "app": "notes",
+        "events": [
+            {
+                "event": FILE_EVENT_CREATED,
+                "filter": {"event.node.path": "/^\\/.*\\/files\\/Notes\\//"},
+            },
+            {
+                "event": FILE_EVENT_WRITTEN,
+                "filter": {"event.node.path": "/^\\/.*\\/files\\/Notes\\//"},
+            },
+            {
+                "event": FILE_EVENT_DELETED,
+                "filter": {"event.node.path": "/^\\/.*\\/files\\/Notes\\//"},
+            },
+        ],
+    },
+    "calendar_sync": {
+        "name": "Calendar Sync",
+        "description": "Real-time synchronization for Calendar events (create, update, delete)",
+        "app": "calendar",
+        "events": [
+            {
+                "event": CALENDAR_EVENT_CREATED,
+                "filter": {},
+            },
+            {
+                "event": CALENDAR_EVENT_UPDATED,
+                "filter": {},
+            },
+            {
+                "event": CALENDAR_EVENT_DELETED,
+                "filter": {},
+            },
+        ],
+    },
+    "tables_sync": {
+        "name": "Tables Sync",
+        "description": "Real-time synchronization for Tables rows (add, update, delete)",
+        "app": "tables",
+        "events": [
+            {
+                "event": TABLES_EVENT_ROW_ADDED,
+                "filter": {},
+            },
+            {
+                "event": TABLES_EVENT_ROW_UPDATED,
+                "filter": {},
+            },
+            {
+                "event": TABLES_EVENT_ROW_DELETED,
+                "filter": {},
+            },
+        ],
+    },
+    "forms_sync": {
+        "name": "Forms Sync",
+        "description": "Real-time synchronization for Forms submissions",
+        "app": "forms",
+        "events": [
+            {
+                "event": FORMS_EVENT_FORM_SUBMITTED,
+                "filter": {},
+            },
+        ],
+    },
+    "files_sync": {
+        "name": "All Files Sync",
+        "description": "Real-time synchronization for all file operations (create, update, delete)",
+        "app": "files",
+        "events": [
+            {
+                "event": FILE_EVENT_CREATED,
+                "filter": {},
+            },
+            {
+                "event": FILE_EVENT_WRITTEN,
+                "filter": {},
+            },
+            {
+                "event": FILE_EVENT_DELETED,
+                "filter": {},
+            },
+        ],
+    },
+}
+
+
+def get_preset(preset_id: str) -> WebhookPreset | None:
+    """Get a webhook preset by ID.
+
+    Args:
+        preset_id: Preset identifier (e.g., "notes_sync", "calendar_sync")
+
+    Returns:
+        Webhook preset configuration or None if not found
+    """
+    return WEBHOOK_PRESETS.get(preset_id)
+
+
+def list_presets() -> List[tuple[str, WebhookPreset]]:
+    """Get all available webhook presets.
+
+    Returns:
+        List of (preset_id, preset_config) tuples
+    """
+    return list(WEBHOOK_PRESETS.items())
+
+
+def get_preset_events(preset_id: str) -> List[str]:
+    """Get list of event class names for a preset.
+
+    Args:
+        preset_id: Preset identifier
+
+    Returns:
+        List of fully qualified event class names
+    """
+    preset = get_preset(preset_id)
+    if not preset:
+        return []
+    return [event_config["event"] for event_config in preset["events"]]
+
+
+def filter_presets_by_installed_apps(
+    installed_apps: list[str],
+) -> List[tuple[str, WebhookPreset]]:
+    """Filter webhook presets to only show those for installed apps.
+
+    Args:
+        installed_apps: List of installed app names (e.g., ["notes", "calendar", "forms"])
+
+    Returns:
+        List of (preset_id, preset_config) tuples for presets whose apps are installed
+    """
+    filtered = []
+    for preset_id, preset in WEBHOOK_PRESETS.items():
+        app_name = preset["app"]
+        # "files" is always available (core functionality)
+        if app_name == "files" or app_name in installed_apps:
+            filtered.append((preset_id, preset))
+    return filtered

nextcloud_mcp_server/vector/__init__.py

@@ -0,0 +1,16 @@
+"""Vector database and background sync package."""
+
+from .document_chunker import DocumentChunker
+from .processor import process_document, processor_task
+from .qdrant_client import get_qdrant_client
+from .scanner import DocumentTask, scan_user_documents, scanner_task
+
+__all__ = [
+    "get_qdrant_client",
+    "DocumentChunker",
+    "scanner_task",
+    "scan_user_documents",
+    "DocumentTask",
+    "processor_task",
+    "process_document",
+]