### Run Initial Setup and Benchmark

Source: https://github.com/cbcoutinho/nextcloud-mcp-server/blob/master/tests/load/README_OAUTH.md

Execute the load testing framework. Ensure Docker Compose is running before starting the benchmark with a specified number of users and duration. Always clean up test users after the benchmark.

```bash
# 1. Ensure docker-compose is running
docker-compose up -d

# 2. Run a benchmark with 2 users for 30 seconds
uv run python -m tests.load.oauth_benchmark --users 2 --duration 30

# 3. Clean up test users (IMPORTANT - always run after benchmark)
uv run python -m tests.load.cleanup_loadtest_users

# Optional: Verify cleanup
uv run python -m tests.load.cleanup_loadtest_users --dry-run
```

--------------------------------

### Setup Keycloak and OIDC Provider

Source: https://github.com/cbcoutinho/nextcloud-mcp-server/blob/master/CLAUDE.md

Starts Keycloak and MCP services, retrieves OIDC configuration, and registers Keycloak as an OIDC provider for the MCP server.

```bash
docker compose up -d keycloak app mcp-keycloak
```

```bash
curl http://localhost:8888/realms/nextcloud-mcp/.well-known/openid-configuration
```

```bash
docker compose exec app php occ user_oidc:provider keycloak
```

--------------------------------

### Install Dependencies

Source: https://github.com/cbcoutinho/nextcloud-mcp-server/blob/master/CLAUDE.md

Installs the project's dependencies using uv.

```bash
uv sync                # Install dependencies
```

--------------------------------

### Single-User BasicAuth: Before v0.58.0

Source: https://github.com/cbcoutinho/nextcloud-mcp-server/blob/master/docs/configuration-migration-v2.md

Example environment variables for a single-user basic authentication setup before version 0.58.0, including semantic search configuration.

```bash
NEXTCLOUD_HOST=http://localhost:8080
NEXTCLOUD_USERNAME=admin
NEXTCLOUD_PASSWORD=password
VECTOR_SYNC_ENABLED=true
QDRANT_LOCATION=:memory:
OLLAMA_BASE_URL=http://ollama:11434
```

--------------------------------

### Example Output of Concurrent User Creation and OAuth Authentication

Source: https://github.com/cbcoutinho/nextcloud-mcp-server/blob/master/tests/load/README_OAUTH.md

Shows the expected output when creating and authenticating multiple users concurrently for performance testing. This demonstrates the parallel execution of user setup tasks.

```text
Step 5/6: Creating 4 users and acquiring OAuth tokens...
(Running concurrently for faster setup)

  [1/4] Creating user 'loadtest_user_1'...
  [2/4] Creating user 'loadtest_user_2'...
  [3/4] Creating user 'loadtest_user_3'...
  [4/4] Creating user 'loadtest_user_4'...
  ✓ User 'loadtest_user_4' authenticated
  ✓ User 'loadtest_user_2' authenticated
  ✓ User 'loadtest_user_1' authenticated
  ✓ User 'loadtest_user_3' authenticated

✓ Successfully created and authenticated 4 users
```

--------------------------------

### Verify Installation with uv

Source: https://github.com/cbcoutinho/nextcloud-mcp-server/blob/master/docs/installation.md

Verifies the Nextcloud MCP server installation by running the help command using uv.

```bash
# With uv
uv run nextcloud-mcp-server --help
```

--------------------------------

### Start Server with Docker Compose

Source: https://github.com/cbcoutinho/nextcloud-mcp-server/blob/master/docs/configuration-migration-v2.md

Command to start the Nextcloud MCP server using Docker Compose.

```bash
# Start server
docker-compose up mcp
```

--------------------------------

### Multi-User OAuth: Before v0.58.0

Source: https://github.com/cbcoutinho/nextcloud-mcp-server/blob/master/docs/configuration-migration-v2.md

Example environment variables for a multi-user OAuth setup before version 0.58.0, highlighting the need for both offline access and semantic search variables.

```bash
NEXTCLOUD_HOST=https://nextcloud.example.com
NEXTCLOUD_USERNAME=
NEXTCLOUD_PASSWORD=

# Both variables required - confusing!
ENABLE_OFFLINE_ACCESS=true
VECTOR_SYNC_ENABLED=true

TOKEN_ENCRYPTION_KEY=your-key-here
TOKEN_STORAGE_DB=/app/data/tokens.db
QDRANT_URL=http://qdrant:6333
OLLAMA_BASE_URL=http://ollama:11434
NEXTCLOUD_OIDC_CLIENT_ID=mcp-server
NEXTCLOUD_OIDC_CLIENT_SECRET=secret
```

--------------------------------

### Install Development Dependencies

Source: https://github.com/cbcoutinho/nextcloud-mcp-server/blob/master/CLAUDE.md

Installs the project's dependencies along with development-specific dependencies using uv.

```bash
uv sync --group dev    # Install with dev dependencies
```

--------------------------------

### Complete Example: Create Note with Embedded Image

Source: https://github.com/cbcoutinho/nextcloud-mcp-server/blob/master/docs/nextcloud_notes_image_embedding.md

This comprehensive example demonstrates the full workflow: creating a note, uploading an image as an attachment, and updating the note's content to embed the image using Markdown syntax. It requires initializing the NextcloudClient and reading image file content.

```python
from nextcloud_mcp_server.client import NextcloudClient
import os

# Create client
client = NextcloudClient.from_env()

# 1. Create the note
note = client.notes_create_note(
    title="Note with Embedded Image",
    content="# Image Example\n\nThis note will have an embedded image.",
    category="Documentation"
)
note_id = note["id"]
note_etag = note["etag"]

# 2. Read image content
with open("example.png", "rb") as f:
    image_content = f.read()

# 3. Upload image as attachment
client.add_note_attachment(
    note_id=note_id,
    filename="example.png",
    content=image_content,
    mime_type="image/png"
)

# 4. Update note content to include image reference
updated_content = f"""# Image Example

This note has an embedded image below:

![Example Image](.attachments.{note_id}/example.png)
"""

# 5. Update the note with image reference
client.notes_update_note(
    note_id=note_id,
    etag=note_etag,
    content=updated_content
)
```

--------------------------------

### Explicit Mode Configuration Example

Source: https://github.com/cbcoutinho/nextcloud-mcp-server/blob/master/docs/configuration-migration-v2.md

Example of setting the deployment mode and Nextcloud host explicitly. This clarifies the server's operational mode, such as OAuth via Login Flow.

```bash
MCP_DEPLOYMENT_MODE=login_flow
NEXTCLOUD_HOST=https://nextcloud.example.com
```

--------------------------------

### Starting Docker Compose with Qdrant Profile

Source: https://github.com/cbcoutinho/nextcloud-mcp-server/blob/master/docs/configuration.md

Command to start the Docker Compose services, specifically enabling the Qdrant profile to include the Qdrant service.

```bash
docker-compose --profile qdrant up
```

--------------------------------

### Install uv Package Manager

Source: https://github.com/cbcoutinho/nextcloud-mcp-server/blob/master/docs/installation.md

Installs the uv package manager, recommended for installing dependencies. Supports macOS/Linux and Windows.

```bash
# Install uv (recommended)
# On macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# On Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
```

--------------------------------

### Start Docker Stack

Source: https://github.com/cbcoutinho/nextcloud-mcp-server/blob/master/docs/testing-oidc-consent.md

Commands to start the Nextcloud Docker stack, including downing existing containers for a fresh start and then bringing them up in detached mode. Monitor logs for initialization.

```bash
cd ~/Projects/nextcloud-mcp-server

# Start fresh (recommended for first test)
docker compose down -v
docker compose up -d

# Wait for initialization (check logs)
docker compose logs -f app
```

--------------------------------

### Pre-registered MCP Client Example

Source: https://github.com/cbcoutinho/nextcloud-mcp-server/blob/master/docs/ADR-004-mcp-application-oauth.md

This is an example of how an administrator would pre-register known MCP clients directly within the Identity Provider (e.g., Keycloak or Nextcloud). The comment indicates common client IDs that might be registered.

```bash
# Admin pre-registers known MCP clients in Keycloak/Nextcloud
# Client IDs: "claude-desktop", "continue-dev", "zed-editor", etc.
```

--------------------------------

### Document Chunking Examples

Source: https://github.com/cbcoutinho/nextcloud-mcp-server/blob/master/docs/configuration.md

Examples demonstrating different document chunking configurations for precise matching, balanced approach, and handling long documents.

```dotenv
# Precise matching for short notes
DOCUMENT_CHUNK_SIZE=1024
DOCUMENT_CHUNK_OVERLAP=100
```

```dotenv
# Default balanced configuration
DOCUMENT_CHUNK_SIZE=2048
DOCUMENT_CHUNK_OVERLAP=200
```

```dotenv
# More context for long documents
DOCUMENT_CHUNK_SIZE=4096
DOCUMENT_CHUNK_OVERLAP=400
```

--------------------------------

### Nextcloud Settings Controller Example

Source: https://github.com/cbcoutinho/nextcloud-mcp-server/blob/master/docs/ADR-018-nextcloud-php-app-for-settings-ui.md

Example of a PHP controller for handling personal settings in a Nextcloud app. This controller would fetch data using the McpServerClient and render the settings view.

```php
<?php

namespace MCPServerSettings\Controller;

use OCP\AppFramework\App;
use OCP\AppFramework\Controller;
use OCP\AppFramework\Http\Request;
use OCP\AppFramework\Http\Response;
use MCPServerSettings\Service\McpServerClient;

class PersonalSettingsController extends Controller {

    private McpServerClient $mcpClient;

    public function __construct(string $appName, Request $request, McpServerClient $mcpClient) {
        parent::__construct($appName, $request);
        $this->mcpClient = $mcpClient;
    }

    /**
     * @NoAdminRequired
     * @PublicPage
     */
    public function index(): Response {
        $users = $this->mcpClient->getUsers();
        return new Response($this->createTemplate('settings/personal'), ['users' => $users]);
    }
}

```

--------------------------------

### Starting Docker Compose with Default In-Memory Qdrant

Source: https://github.com/cbcoutinho/nextcloud-mcp-server/blob/master/docs/configuration.md

Command to start Docker Compose when using the default in-memory mode for Qdrant, which does not require a specific profile.

```bash
docker-compose up
```

--------------------------------

### Start Docker Compose with Login Flow Profile

Source: https://github.com/cbcoutinho/nextcloud-mcp-server/blob/master/docs/login-flow-v2.md

Starts the Nextcloud MCP server with the login-flow profile enabled. The server will listen on http://localhost:8004.

```bash
docker compose --profile login-flow up -d
```

--------------------------------

### Scanner Logs Example

Source: https://github.com/cbcoutinho/nextcloud-mcp-server/blob/master/docs/semantic-search-architecture.md

Example log output from the vector sync scanner, showing its startup, document scanning progress, and enqueuing of documents for processing.

```log
[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
```

--------------------------------

### Explicit Mode Selection Example

Source: https://github.com/cbcoutinho/nextcloud-mcp-server/blob/master/docs/configuration-migration-v2.md

Demonstrates the use of MCP_DEPLOYMENT_MODE for removing ambiguity and improving configuration validation.

```bash

```

--------------------------------

### Run Server with Docker (Bind to All Interfaces)

Source: https://github.com/cbcoutinho/nextcloud-mcp-server/blob/master/docs/running.md

Starts the server and binds it to all network interfaces (0.0.0.0), making it accessible from other devices on the network. Uses OAuth mode.

```bash
# Bind to all interfaces (accessible from network)
docker run -p 0.0.0.0:8000:8000 --env-file .env --rm \
  ghcr.io/cbcoutinho/nextcloud-mcp-server:latest --oauth
```

--------------------------------

### Multi-User OAuth WITHOUT Semantic Search: Before v0.58.0

Source: https://github.com/cbcoutinho/nextcloud-mcp-server/blob/master/docs/configuration-migration-v2.md

Example environment variables for a multi-user OAuth setup before version 0.58.0, where background operations are enabled independently.

```bash
NEXTCLOUD_HOST=https://nextcloud.example.com
NEXTCLOUD_USERNAME=
NEXTCLOUD_PASSWORD=

# Enable background operations for future features
ENABLE_OFFLINE_ACCESS=true

TOKEN_ENCRYPTION_KEY=your-key-here
TOKEN_STORAGE_DB=/app/data/tokens.db
NEXTCLOUD_OIDC_CLIENT_ID=mcp-server
NEXTCLOUD_OIDC_CLIENT_SECRET=secret
```

--------------------------------

### Example of Complex Configuration for Multi-user OAuth with Semantic Search

Source: https://github.com/cbcoutinho/nextcloud-mcp-server/blob/master/docs/ADR-021-configuration-consolidation.md

This bash snippet shows the configuration required before consolidation, highlighting confusing variable names and redundant settings.

```bash
NEXTCLOUD_HOST=https://nextcloud.example.com
ENABLE_OFFLINE_ACCESS=true      # Why is this needed?
VECTOR_SYNC_ENABLED=true        # And this separately?
QDRANT_URL=http://qdrant:6333
TOKEN_ENCRYPTION_KEY=<key>
TOKEN_STORAGE_DB=/path/to/tokens.db
```

--------------------------------

### Run Server with Docker (OAuth on Custom Port)

Source: https://github.com/cbcoutinho/nextcloud-mcp-server/blob/master/docs/running.md

Starts the server in OAuth mode and maps it to a custom host port (8080 in this example) while the container uses port 8000.

```bash
# OAuth on a custom port
docker run -p 127.0.0.1:8080:8000 --env-file .env --rm \
  ghcr.io/cbcoutinho/nextcloud-mcp-server:latest --oauth
```

--------------------------------

### Check Server Readiness Probe

Source: https://github.com/cbcoutinho/nextcloud-mcp-server/blob/master/docs/running.md

Use this command to check if the server is ready to handle requests, including its ability to connect to Nextcloud and Qdrant. Returns 503 if dependencies fail.

```bash
curl http://localhost:8000/health/ready
```

--------------------------------

### Configuration Validation Functions

Source: https://github.com/cbcoutinho/nextcloud-mcp-server/blob/master/docs/ADR-020-deployment-modes-and-configuration-validation.md

Python functions for detecting the authentication mode and validating the application's configuration settings. These functions are crucial for ensuring the server starts with a correct and consistent setup.

```python
def detect_auth_mode(settings: Settings) -> AuthMode:
    """Detect authentication mode from configuration.

    Priority (most specific to most general):
    1. Smithery (explicit flag)
    2. Token exchange (most specific OAuth mode)
    3. Multi-user BasicAuth
    4. Single-user BasicAuth
    5. OAuth single-audience (default OAuth mode)
    """

def validate_configuration(settings: Settings) -> tuple[AuthMode, list[str]]:
    """Validate configuration for detected mode.

    Returns:
        Tuple of (detected_mode, list_of_errors)
        Empty list means valid configuration.
    """
```

--------------------------------

### Multi-User OAuth WITHOUT Semantic Search: After v0.58.0

Source: https://github.com/cbcoutinho/nextcloud-mcp-server/blob/master/docs/configuration-migration-v2.md

Example environment variables for a multi-user OAuth setup after version 0.58.0, without semantic search enabled, but with the option for explicit mode declaration.

```bash
NEXTCLOUD_HOST=https://nextcloud.example.com
NEXTCLOUD_USERNAME=
NEXTCLOUD_PASSWORD=

# Optional: Explicit mode declaration
MCP_DEPLOYMENT_MODE=login_flow

```

--------------------------------

### Example settings.local.toml

Source: https://github.com/cbcoutinho/nextcloud-mcp-server/blob/master/docs/ADR-025-dynaconf-configuration-management.md

This TOML file is for personal developer overrides and is gitignored. It allows local adjustments to settings without affecting the main configuration.

```toml
# Example developer overrides
[default]
log_level = "DEBUG"
ollama_base_url = "http://localhost:11434"
```

--------------------------------

### Expected Log Output for Multi-User OAuth + Semantic Search

Source: https://github.com/cbcoutinho/nextcloud-mcp-server/blob/master/docs/configuration-migration-v2.md

Example of expected log messages after starting the server with multi-user OAuth and semantic search enabled, indicating correct configuration and feature enablement.

```text
INFO: Using explicit deployment mode: login_flow
INFO: Automatically enabled background operations for semantic search in multi-user mode.
INFO: Vector sync enabled. Starting background scanner...
```

--------------------------------

### Qdrant Collection Naming Example (Default Hostname)

Source: https://github.com/cbcoutinho/nextcloud-mcp-server/blob/master/docs/configuration.md

Illustrates Qdrant collection name generation when OTEL_SERVICE_NAME is not configured, falling back to the hostname.

```bash
# Simple Docker deployment (OTEL not configured)
# hostname=mcp-container
OLLAMA_EMBEDDING_MODEL=all-minilm
# → Collection: "mcp-container-all-minilm"
```

--------------------------------

### Verify Installation with pip/venv

Source: https://github.com/cbcoutinho/nextcloud-mcp-server/blob/master/docs/installation.md

Verifies the Nextcloud MCP server installation by running the help command when installed via pip.

```bash
# With pip/venv
nextcloud-mcp-server --help
```

--------------------------------

### Create and Manage Deck Project Elements

Source: https://github.com/cbcoutinho/nextcloud-mcp-server/blob/master/docs/deck.md

This snippet demonstrates the creation of a new project board, workflow stacks, task cards with details, and labels. It also shows how to assign labels and users to cards, and how to move cards through the workflow by reordering them between stacks.

```python
# Create a new project board
await deck_create_board(title="Website Redesign", color="1976D2")

# Create workflow stacks
await deck_create_stack(board_id=1, title="To Do", order=1)
await deck_create_stack(board_id=1, title="In Progress", order=2)
await deck_create_stack(board_id=1, title="Done", order=3)

# Create task cards with details
await deck_create_card(
    board_id=1,
    stack_id=1,
    title="Design new homepage",
    description="Create mockups for the new homepage layout",
    type="plain",
    order=1,
    duedate="2025-08-15T17:00:00"
)

# Create and assign labels for organization
await deck_create_label(board_id=1, title="High Priority", color="F44336")
await deck_create_label(board_id=1, title="UI/UX", color="9C27B0")

# Assign labels and users to cards
await deck_assign_label_to_card(board_id=1, stack_id=1, card_id=1, label_id=1)
await deck_assign_user_to_card(board_id=1, stack_id=1, card_id=1, user_id="designer")

# Move cards through workflow
await deck_reorder_card(
    board_id=1,
    stack_id=1,        # From "To Do"
    card_id=1,
    order=1,
    target_stack_id=2  # To "In Progress"
)

# Update task progress
await deck_update_card(
    board_id=1,
    stack_id=2,
    card_id=1,
    description="Homepage mockups completed, starting development",
    order=1
)

# Complete tasks
await deck_reorder_card(
    board_id=1,
    stack_id=2,        # From "In Progress"  
    card_id=1,
    order=1,
    target_stack_id=3  # To "Done"
)

# Archive completed cards
await deck_archive_card(board_id=1, stack_id=3, card_id=1)
```

--------------------------------

### Bash: OAuth and Vector Database Configuration via Environment Variables

Source: https://github.com/cbcoutinho/nextcloud-mcp-server/blob/master/docs/ADR-002-vector-sync-authentication.md

Sets up essential environment variables for OAuth discovery, client credentials, Nextcloud host, and Qdrant vector database connection.

```bash
# OAuth Configuration (Required for Background Sync in OAuth Mode)
# Requires external OIDC provider with client_credentials support
OIDC_DISCOVERY_URL=http://keycloak:8080/realms/nextcloud-mcp/.well-known/openid-configuration
OIDC_CLIENT_ID=nextcloud-mcp-server
OIDC_CLIENT_SECRET=<secure-secret>
NEXTCLOUD_HOST=http://app:80

# Tier selection is automatic:
# - Tier 1 (service_account): Always available if client has service account enabled
# - Tier 2/3 (token_exchange): Used if provider supports RFC 8693 token exchange

# Vector Database
QDRANT_URL=http://qdrant:6333
QDRANT_API_KEY=<api-key>

# Sync Configuration
SYNC_INTERVAL_SECONDS=300
SYNC_BATCH_SIZE=100

```

--------------------------------

### Install Dependencies with pip

Source: https://github.com/cbcoutinho/nextcloud-mcp-server/blob/master/docs/installation.md

Installs project dependencies using pip within a virtual environment. Supports development mode installation.

```bash
# Create virtual environment
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install in development mode
pip install -e .

# Install development dependencies (optional)
pip install -e ".[dev]"
```

--------------------------------

### Install Dependencies with uv

Source: https://github.com/cbcoutinho/nextcloud-mcp-server/blob/master/docs/installation.md

Installs project dependencies using the uv package manager. Includes an option to install development dependencies.

```bash
# Install dependencies
uv sync

# Install development dependencies (optional)
uv sync --group dev
```

--------------------------------

### Plugin System with Entry Points

Source: https://github.com/cbcoutinho/nextcloud-mcp-server/blob/master/docs/ADR-015-unified-provider-architecture.md

Another alternative explored was a plugin system using Python entry points for dynamic provider registration. This approach allows for extensible provider management and the potential for third-party providers.

```python
# setup.py
entry_points={
    'nextcloud_mcp.providers': [
        'ollama = nextcloud_mcp_server.providers.ollama:OllamaProvider',
        'bedrock = nextcloud_mcp_server.providers.bedrock:BedrockProvider',
    ]
}
```

--------------------------------

### Example CLI Usage: BasicAuth Mode with Specific Apps

Source: https://github.com/cbcoutinho/nextcloud-mcp-server/blob/master/docs/configuration.md

Shows how to run the server in BasicAuth mode, enabling only the 'notes' and 'calendar' Nextcloud app APIs. This is useful for minimizing the server's footprint.

```bash
# BasicAuth mode with specific apps only
uv run nextcloud-mcp-server --no-oauth \
  --enable-app notes \
  --enable-app calendar
```

--------------------------------

### Run Server with Docker (BasicAuth with Specific Apps)

Source: https://github.com/cbcoutinho/nextcloud-mcp-server/blob/master/docs/running.md

Starts the server in BasicAuth mode and enables only specific applications ('notes', 'webdav').

```bash
# BasicAuth with specific apps
docker run -p 127.0.0.1:8000:8000 --env-file .env --rm \
  ghcr.io/cbcoutinho/nextcloud-mcp-server:latest \
  --enable-app notes --enable-app webdav
```

--------------------------------

### Create and edit .env file

Source: https://github.com/cbcoutinho/nextcloud-mcp-server/blob/master/docs/troubleshooting.md

Copies a sample .env file and opens it for editing using nano. This is useful when the .env file is missing or needs to be initialized.

```bash
# Create .env from sample
cp env.sample .env

# Edit with your Nextcloud details
nano .env  # or vim, code, etc.

# Ensure you're in the correct directory when running commands
pwd  # Should be in the project directory containing .env
```

--------------------------------

### Start Docker Compose Service

Source: https://github.com/cbcoutinho/nextcloud-mcp-server/blob/master/docs/installation.md

Starts the Nextcloud MCP server service defined in docker-compose.yml in detached mode.

```bash
docker-compose up -d
```

--------------------------------

### Conventional Commit Message Examples

Source: https://github.com/cbcoutinho/nextcloud-mcp-server/blob/master/CONTRIBUTING.md

Examples of commit messages following the conventional commits specification. Use these to categorize your changes.

```bash
feat: add new feature
```

```bash
feat(mcp): add calendar sync API
```

```bash
fix: resolve authentication bug
```

```bash
docs: update README
```

--------------------------------

### Start MCP Inspector

Source: https://github.com/cbcoutinho/nextcloud-mcp-server/blob/master/docs/running.md

Starts the MCP Inspector tool using npx. This browser-based tool is used for testing MCP servers.

```bash
npx @modelcontextprotocol/inspector
```

--------------------------------

### Run Server with Docker (OAuth with Static Client)

Source: https://github.com/cbcoutinho/nextcloud-mcp-server/blob/master/docs/running.md

Starts the server in OAuth mode using pre-registered static client credentials. This is the preferred method for OAuth client configuration.

```bash
# OAuth with static (pre-registered) client — preferred
docker run -p 127.0.0.1:8000:8000 --env-file .env --rm \
  -e NEXTCLOUD_OIDC_CLIENT_ID=abc123 \
  -e NEXTCLOUD_OIDC_CLIENT_SECRET=xyz789 \
  ghcr.io/cbcoutinho/nextcloud-mcp-server:latest --oauth
```

--------------------------------

### Explicit Mode Declaration Example

Source: https://github.com/cbcoutinho/nextcloud-mcp-server/blob/master/docs/configuration-migration-v2.md

Example of adding an explicit mode declaration to the .env file to prevent unexpected mode detection.

```bash
MCP_DEPLOYMENT_MODE=multi_user_basic
```

--------------------------------

### Bedrock Embedding Request Example (Titan)

Source: https://github.com/cbcoutinho/nextcloud-mcp-server/blob/master/docs/ADR-015-unified-provider-architecture.md

Example of the JSON payload structure for a Bedrock embedding request when using a Titan model.

```json
{"inputText": text}
```

--------------------------------

### Run Server with Docker (OAuth with Dynamic Client Registration)

Source: https://github.com/cbcoutinho/nextcloud-mcp-server/blob/master/docs/running.md

Starts the server in OAuth mode, falling back to dynamic client registration if static credentials are not provided. This method is used when the server self-registers with the IdP.

```bash
# OAuth with auto-registration (DCR) — used when static creds are absent
docker run -p 127.0.0.1:8000:8000 --env-file .env --rm \
  ghcr.io/cbcoutinho/nextcloud-mcp-server:latest --oauth
```

--------------------------------

### Processor Logs Example

Source: https://github.com/cbcoutinho/nextcloud-mcp-server/blob/master/docs/semantic-search-architecture.md

Example log output from the document processor, indicating the processing of a document, embedding generation, and successful storage of the vector.

```log
[INFO] Processing document: note_123
[DEBUG] Generated embedding (768 dimensions)
[INFO] Stored vector in Qdrant: note_123
```

--------------------------------

### Run Nextcloud MCP Server Locally with uvx

Source: https://github.com/cbcoutinho/nextcloud-mcp-server/blob/master/README.md

Run the server locally using uvx for quick setup. Ensure you set the NEXTCLOUD_HOST, NEXTCLOUD_USERNAME, and NEXTCLOUD_PASSWORD environment variables.

```bash
NEXTCLOUD_HOST=https://your.nextcloud.instance.com \
NEXTCLOUD_USERNAME=your_username \
NEXTCLOUD_PASSWORD=your_app_password \
  uvx nextcloud-mcp-server run --transport stdio
```

--------------------------------

### Bedrock Generation Request Example (Claude)

Source: https://github.com/cbcoutinho/nextcloud-mcp-server/blob/master/docs/ADR-015-unified-provider-architecture.md

Example of the JSON payload structure for a Bedrock text generation request when using a Claude model.

```json
{
    "anthropic_version": "bedrock-2023-05-31",
    "max_tokens": max_tokens,
    "temperature": 0.7,
    "messages": [{"role": "user", "content": prompt}]
}
```

--------------------------------

### Configure Qdrant for In-Memory Mode

Source: https://github.com/cbcoutinho/nextcloud-mcp-server/blob/master/docs/semantic-search-architecture.md

Use this configuration for the fastest startup and no disk I/O. Note that all vectors are lost when the server restarts.

```bash
ENABLE_SEMANTIC_SEARCH=true
QDRANT_LOCATION not set → defaults to :memory:
```

--------------------------------

### Example CLI Usage: OAuth Mode

Source: https://github.com/cbcoutinho/nextcloud-mcp-server/blob/master/docs/configuration.md

Demonstrates how to run the server in OAuth mode with custom client ID, secret, and a non-default port. This is useful for testing OAuth configurations.

```bash
# OAuth mode with custom client and port
uv run nextcloud-mcp-server --oauth \
  --oauth-client-id abc123 \
  --oauth-client-secret xyz789 \
  --port 8080
```

--------------------------------

### Embedding Model Switching Workflow Example

Source: https://github.com/cbcoutinho/nextcloud-mcp-server/blob/master/docs/semantic-search-architecture.md

Demonstrates the command-line steps and expected outcomes when switching the embedding model. This includes setting the environment variable and the resulting collection creation and re-embedding process.

```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
```

--------------------------------

### Manual Provisioning Flow (Before)

Source: https://github.com/cbcoutinho/nextcloud-mcp-server/blob/master/docs/ADR-006-progressive-consent-elicitation.md

Illustrates the multi-step manual process required for provisioning Nextcloud access before implementing progressive elicitation. This flow involves several user-assistant interactions and manual URL handling.

```text
User: "List my notes"
Assistant: *calls nc_notes_list_notes*
Server: Error - not provisioned
Assistant: "You need to provision access first. Let me do that."
Assistant: *calls provision_nextcloud_access*
Server: {authorization_url: "https://..."}
Assistant: "Please visit this URL: https://..."
User: *copies URL, opens browser, completes OAuth*
User: "OK, I'm done"
Assistant: *calls nc_notes_list_notes again*
Server: Success! [notes...]
```

--------------------------------

### MCP Access Token Example

Source: https://github.com/cbcoutinho/nextcloud-mcp-server/blob/master/docs/ADR-004-mcp-application-oauth.md

Example structure of an MCP access token issued by the IdP. Note the 'aud' (audience) claim is specific to 'mcp-server'.

```json
# MCP Access Token (from IdP)
{
  "aud": "mcp-server",      # Single audience ONLY
  "sub": "user-123",
  "scope": "mcp:full",
  "exp": 1234567890
}
```

--------------------------------

### Run Server with Docker (Persistent Token Storage)

Source: https://github.com/cbcoutinho/nextcloud-mcp-server/blob/master/docs/running.md

Starts the server in OAuth mode and mounts a local volume ('./data') to persist OAuth tokens, ensuring they are not lost when the container is removed.

```bash
# Mount volume for persistent OAuth token storage
docker run -p 127.0.0.1:8000:8000 --env-file .env \
  -v $(pwd)/data:/app/data \
  --rm ghcr.io/cbcoutinho/nextcloud-mcp-server:latest --oauth
```

--------------------------------

### Error Logs Example

Source: https://github.com/cbcoutinho/nextcloud-mcp-server/blob/master/docs/semantic-search-architecture.md

Example log output for errors encountered during embedding generation or vector storage, including connection issues and model not found errors.

```log
[ERROR] Failed to generate embedding for note_123: Connection timeout
[WARN] Qdrant connection lost, retrying...
[ERROR] Ollama embedding failed: Model not found
```

--------------------------------

### Run Server with Multiple Apps Enabled

Source: https://github.com/cbcoutinho/nextcloud-mcp-server/blob/master/docs/running.md

Enables multiple specified apps: 'notes', 'calendar', and 'contacts'. This allows for a customized server setup.

```bash
docker run -p 127.0.0.1:8000:8000 --env-file .env --rm \
  ghcr.io/cbcoutinho/nextcloud-mcp-server:latest --oauth \
  --enable-app notes --enable-app calendar --enable-app contacts
```

--------------------------------

### Nextcloud Access Token Example

Source: https://github.com/cbcoutinho/nextcloud-mcp-server/blob/master/docs/ADR-004-mcp-application-oauth.md

Example structure of a Nextcloud access token obtained via refresh grant. The 'aud' (audience) claim is specific to 'nextcloud'.

```json
# Nextcloud Access Token (obtained via refresh)
{
  "aud": "nextcloud",        # Different audience
  "sub": "user-123",
  "scope": "notes:read calendar:write",
  "exp": 1234567890
}
```