test: Inc delay for alice

Enable OAuth2 using Nextcloud user_oidc/oidc apps

.dockerignore

@@ -1,8 +1,7 @@
 *
 
 !pyproject.toml
-!poetry.lock
 !README.md
 !uv.lock
 
-!nextcloud_mcp_server/
+!nextcloud_mcp_server/**/*.py

.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@6cbd405e2c4e67a21c47fa9e383d020e4e28b836 # v2.3.3
+        uses: softprops/action-gh-release@6da8fa9354ddfdc4aeace5fc48d7f679b5214090 # v2.4.1
         with:
           body_path: "body.md"
           tag_name: v${{ env.REVISION }}

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

@@ -37,7 +37,7 @@ jobs:
 
       - name: Log in to GitHub Container Registry
         if: github.event_name != 'pull_request'
-        uses: docker/login-action@184bdaa0721073962dff0199f1fb9940f07167d1 # v3
+        uses: docker/login-action@5e57cd118135c172c3672efd75eb46360885c0ef # v3
         with:
           registry: ghcr.io
           username: ${{ github.actor }}

.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@557e51de59eb14aaaba2ed9621916900a91d50c6 # v6
+        uses: astral-sh/setup-uv@3259c6206f993105e3a61b142c2d97bf4b9ef83d # v7.1.0
       - name: Check format
         run: |
           uv run --frozen ruff format --diff
@@ -27,11 +27,17 @@ jobs:
       - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
 
       - name: Run docker compose
-        uses: hoverkraft-tech/compose-action@40041ff1b97dbf152cd2361138c2b03fa29139df # v2.3.0
+        uses: hoverkraft-tech/compose-action@3846bcd61da338e9eaaf83e7ed0234a12b099b72 # v2.4.1
         with:
           compose-file: "./docker-compose.yml"
+          up-flags: "--build"
+
       - name: Install the latest version of uv
-        uses: astral-sh/setup-uv@557e51de59eb14aaaba2ed9621916900a91d50c6 # v6
+        uses: astral-sh/setup-uv@3259c6206f993105e3a61b142c2d97bf4b9ef83d # v7.1.0
+
+      - name: Install Playwright dependencies
+        run: |
+          uv run playwright install firefox --with-deps
 
       - name: Wait for service to be ready
         run: |
@@ -56,4 +62,4 @@ jobs:
           NEXTCLOUD_USERNAME: "admin"
           NEXTCLOUD_PASSWORD: "admin"
         run: |
-          uv run --frozen python -m pytest
+          uv run pytest -v --browser firefox

.gitignore

@@ -4,3 +4,6 @@ __pycache__/
 *.env
 .env.local
 .env.*.local
+
+# Generated by pytest used to login users
+.nextcloud_oauth_shared_test_client.json

CHANGELOG.md

@@ -1,3 +1,39 @@
+## v0.13.0 (2025-10-13)
+
+### Feat
+
+- **server**: Experimental support for OAuth2/OIDC authentication
+
+## v0.12.6 (2025-10-11)
+
+### Fix
+
+- **deps**: update dependency mcp to >=1.17,<1.18
+
+## v0.12.5 (2025-10-03)
+
+### Fix
+
+- **deps**: update dependency mcp to >=1.16,<1.17
+
+## v0.12.4 (2025-09-25)
+
+### Fix
+
+- **deps**: update dependency mcp to >=1.15,<1.16
+
+## v0.12.3 (2025-09-23)
+
+### Refactor
+
+- Add tools for all resources to enable tool-only workflows
+
+## v0.12.2 (2025-09-20)
+
+### Refactor
+
+- Add `http` to --transport option
+
 ## v0.12.1 (2025-09-11)
 
 ### Fix

CLAUDE.md

@@ -38,13 +38,21 @@ mcp run --transport sse nextcloud_mcp_server.app:mcp
 # Docker development environment with Nextcloud instance
 docker-compose up
 
-# After code changes, rebuild and restart only the MCP server container
+# After code changes, rebuild and restart the appropriate MCP server container:
+# For basic auth changes (most common) - uses admin credentials
 docker-compose up --build -d mcp
 
+# For OAuth changes - uses OAuth authentication flow
+docker-compose up --build -d mcp-oauth
+
 # Build Docker image
 docker build -t nextcloud-mcp-server .
 ```
 
+**Important: Two MCP Server Containers**
+- **`mcp`** (port 8000): Uses basic auth with admin credentials. Use this for most development and testing.
+- **`mcp-oauth`** (port 8001): Uses OAuth authentication. Only use this when working on OAuth-specific features or tests.
+
 ### Environment Setup
 ```bash
 # Install dependencies
@@ -96,18 +104,23 @@ Each Nextcloud app has a corresponding server module that:
 
 ### Testing Structure
 
-- **Integration tests** in `tests/integration/` - Test real Nextcloud API interactions
+- **Integration tests** in `tests/integration/` and `tests/client/`, `tests/server/` - Test real Nextcloud API interactions
 - **Fixtures** in `tests/conftest.py` - Shared test setup and utilities
 - Tests are marked with `@pytest.mark.integration` for selective running
-- **Important**: Integration tests run against live Docker containers. After making code changes to the MCP server, rebuild only the MCP container with `docker-compose up --build -d mcp` before running tests
+- **Important**: Integration tests run against live Docker containers. After making code changes:
+  - For basic auth tests: rebuild with `docker-compose up --build -d mcp`
+  - For OAuth tests: rebuild with `docker-compose up --build -d mcp-oauth`
 
 #### Testing Best Practices
 - **MANDATORY: Always run tests after implementing features or fixing bugs**
   - Run tests to completion before considering any task complete
   - If tests require modifications to pass, ask for permission before proceeding
-  - Use `docker-compose up --build -d mcp` to rebuild MCP container after code changes
+  - **Rebuild the correct container** after code changes:
+    - For basic auth tests (most common): `docker-compose up --build -d mcp`
+    - For OAuth tests: `docker-compose up --build -d mcp-oauth`
 - **Use existing fixtures** from `tests/conftest.py` to avoid duplicate setup work:
-  - `nc_mcp_client` - MCP client session for tool/resource testing  
+  - `nc_mcp_client` - MCP client session for tool/resource testing (uses `mcp` container)
+  - `nc_mcp_oauth_client` - MCP client session for OAuth testing (uses `mcp-oauth` container)
   - `nc_client` - Direct NextcloudClient for setup/cleanup operations
   - `temporary_note` - Creates and cleans up test notes automatically
   - `temporary_addressbook` - Creates and cleans up test address books
@@ -115,8 +128,66 @@ Each Nextcloud app has a corresponding server module that:
 - **Test specific functionality** after changes:
   - For Notes changes: `uv run pytest tests/integration/test_mcp.py -k "notes" -v`
   - For specific API changes: `uv run pytest tests/integration/test_notes_api.py -v`
+  - For OAuth changes: `uv run pytest tests/server/test_oauth*.py -v` (remember to rebuild `mcp-oauth` container)
 - **Avoid creating standalone test scripts** - use pytest with proper fixtures instead
 
+#### OAuth/OIDC Testing
+OAuth integration tests support both **automated** (Playwright) and **interactive** authentication flows:
+
+**Automated Testing (Default - Recommended for CI/CD):**
+- **Default fixtures**: `nc_oauth_client`, `nc_mcp_oauth_client` now use Playwright automation by default
+- Uses Playwright headless browser automation to complete OAuth flow programmatically
+- **Shared OAuth Client**: All test users authenticate using a single OAuth client (matching MCP server behavior)
+  - Single `client_id`/`client_secret` pair is registered and reused for all test users
+  - Stored in `.nextcloud_oauth_shared_test_client.json` with `force_register=False` for reuse
+  - Reduces OAuth client registrations and matches production MCP server architecture
+- All Playwright fixtures: `playwright_oauth_token`, `nc_oauth_client`, `nc_mcp_oauth_client`, `nc_oauth_client_playwright`, `nc_mcp_oauth_client_playwright`
+- Multi-user fixtures: `alice_oauth_token`, `bob_oauth_token`, `charlie_oauth_token`, `diana_oauth_token`
+  - All use `shared_oauth_client_credentials` fixture for consistent client credentials
+  - Each user gets unique access tokens via same OAuth client (like multiple users using the MCP server)
+- Requires: `NEXTCLOUD_HOST`, `NEXTCLOUD_USERNAME`, `NEXTCLOUD_PASSWORD` environment variables
+- Uses `pytest-playwright-asyncio` for async Playwright fixtures
+- Playwright configuration: Use pytest CLI args like `--browser firefox --headed` to customize
+- Install browsers: `uv run playwright install firefox` (or `chromium`, `webkit`)
+- Example:
+  ```bash
+  # Run all OAuth tests with automated Playwright flow using Firefox
+  uv run pytest tests/server/test_oauth*.py --browser firefox -v
+
+  # Run specific Playwright tests with visible browser for debugging
+  uv run pytest tests/server/test_mcp_oauth.py --browser firefox --headed -v
+
+  # Run with Chromium (default)
+  uv run pytest tests/server/test_oauth*.py -v
+  ```
+
+**Interactive Testing (Manual browser login):**
+- Opens system browser and waits for manual login/authorization
+- Fixtures: `interactive_oauth_token`, `nc_oauth_client_interactive`, `nc_mcp_oauth_client_interactive`
+- Requires: User to complete browser-based login when prompted
+- Useful for: Debugging OAuth flows, testing with 2FA, local development
+- **Automatically skipped in GitHub Actions CI** - Interactive fixtures check for `GITHUB_ACTIONS` environment variable
+- Example:
+  ```bash
+  # Run OAuth tests with interactive flow (will open browser and wait for manual login)
+  uv run pytest tests/client/test_oauth_interactive.py -v
+  ```
+
+**Test Environment Setup:**
+- **Two MCP server containers are available:**
+  - `mcp` (port 8000): Uses basic auth with admin credentials - for most testing
+  - `mcp-oauth` (port 8001): Uses OAuth authentication - for OAuth-specific testing
+- Start OAuth MCP server: `docker-compose up --build -d mcp-oauth`
+- **Important**: When working on OAuth functionality, always rebuild `mcp-oauth` container, not `mcp`
+- Shared OAuth client is registered once and reused across test runs
+- Client credentials cached in `.nextcloud_oauth_shared_test_client.json`
+
+**CI/CD Considerations:**
+- Interactive OAuth tests are automatically skipped when `GITHUB_ACTIONS` environment variable is set
+- Automated Playwright tests will run in CI/CD environments
+- Use Firefox browser in CI: `--browser firefox` (Chromium may have issues with localhost redirects)
+- Shared client approach reduces test time and API calls to Nextcloud
+
 ### Configuration Files
 
 - **`pyproject.toml`** - Python project configuration using uv for dependency management

Dockerfile

@@ -1,4 +1,4 @@
-FROM ghcr.io/astral-sh/uv:0.8.17-python3.11-alpine@sha256:2a2cae80b7d3b3b3c7f94ec3ed91e9b3ca2524a7a429824fbbadd9954fa5d6b6
+FROM ghcr.io/astral-sh/uv:0.9.2-python3.11-alpine@sha256:59c7cb3e4a4fe9ccff6a5bf0d952a0b1b0101adda48e305c02beea3c22256208
 
 WORKDIR /app
 
@@ -6,4 +6,6 @@ COPY . .
 
 RUN uv sync --locked --no-dev
 
-ENTRYPOINT ["/app/.venv/bin/python", "-m", "nextcloud_mcp_server.app", "--host", "0.0.0.0"]
+ENV PYTHONUNBUFFERED=1
+
+ENTRYPOINT ["/app/.venv/bin/nextcloud-mcp-server", "--host", "0.0.0.0"]

README.md

@@ -2,254 +2,235 @@
 
 [![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)
 
-The Nextcloud MCP (Model Context Protocol) server allows Large Language Models (LLMs) like OpenAI's GPT, Google's Gemini, or Anthropic's Claude to interact with your Nextcloud instance. This enables automation of various Nextcloud actions, starting with the Notes API.
+**Enable AI assistants to interact with 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.
 
 ## Features
 
-The server provides integration with multiple Nextcloud apps, enabling LLMs to interact with your Nextcloud data through a rich set of tools and resources.
+### Supported Nextcloud Apps
 
-## Supported Nextcloud Apps
+| App | Support | Features |
+|-----|---------|----------|
+| **Notes** | ✅ Full | Create, read, update, delete, search notes. Handle attachments. |
+| **Calendar** | ✅ Full | Manage events, recurring events, reminders, attendees via CalDAV. |
+| **Contacts** | ✅ Full | CRUD operations for contacts and address books via CardDAV. |
+| **Files (WebDAV)** | ✅ Full | Complete file system access - browse, read, write, organize files. |
+| **Deck** | ✅ Full | Project management - boards, stacks, cards, labels, assignments. |
+| **Tables** | ⚠️ Partial | Row-level operations. Table management not yet supported. |
+| **Tasks** | ❌ Planned | [Issue #73](https://github.com/cbcoutinho/nextcloud-mcp-server/issues/73) |
 
-| App | Support Status | Description |
-|-----|----------------|-------------|
-| **Notes** | ✅ Full Support | Create, read, update, delete, and search notes. Handle attachments via WebDAV. |
-| **Calendar** | ✅ Full Support | Complete calendar integration - create, update, delete events. Support for recurring events, reminders, attendees, and all-day events via CalDAV. |
-| **Tables** | ⚠️ Row Operations | Read table schemas and perform CRUD operations on table rows. Table management not yet supported. |
-| **Files (WebDAV)** | ✅ Full Support | Complete file system access - browse directories, read/write files, create/delete resources. |
-| **Contacts** | ✅ Full Support | Create, read, update, and delete contacts and address books via CardDAV. |
-| **Deck** | ✅ Full Support | Complete project management - boards, stacks, cards, labels, user assignments. Full CRUD operations and advanced features. |
-| **Tasks** | ❌ [Not Started](https://github.com/cbcoutinho/nextcloud-mcp-server/issues/73) | TBD |
+Want to see another Nextcloud app supported? [Open an issue](https://github.com/cbcoutinho/nextcloud-mcp-server/issues) or contribute a pull request!
 
-Is there a Nextcloud app not present in this list that you'd like to be
-included? Feel free to open an issue, or contribute via a pull-request.
+### Authentication
 
-## Available Tools & Resources
+| Mode | Security | Best For |
+|------|----------|----------|
+| **OAuth2/OIDC** ✅ | 🔒 High | Production, multi-user deployments |
+| **Basic Auth** ⚠️ | Lower | Development, testing |
 
-Resources provide read-only access to data for browsing and discovery. Unlike tools, resources are automatically listed by MCP clients and enable LLMs to explore your Nextcloud data structure.
+OAuth2/OIDC provides secure, per-user authentication with access tokens. See [Authentication Guide](docs/authentication.md) for details.
 
-### Core Resources
-| Resource | Description |
-|----------|-------------|
-| `nc://capabilities` | Access Nextcloud server capabilities |
-| `notes://settings` | Access Notes app settings |
-| `nc://Notes/{note_id}/attachments/{attachment_filename}` | Access attachments for notes |
+## Quick Start
 
+### 1. Install
 
-### Tools vs Resources
+```bash
+# Clone the repository
+git clone https://github.com/cbcoutinho/nextcloud-mcp-server.git
+cd nextcloud-mcp-server
 
-**Tools** are for actions and operations:
-- Create, update, delete operations
-- Structured responses with validation
-- Error handling and business logic
-- Examples: `deck_create_card`, `deck_update_stack`
+# Install with uv (recommended)
+uv sync
 
-**Resources** are for data browsing and discovery:
-- Read-only access to existing data
-- Automatic listing by MCP clients
-- Raw data format for exploration
-- Examples: `nc://Deck/boards/{board_id}`, `nc://Deck/boards/{board_id}/stacks`
+# Or using Docker
+docker pull ghcr.io/cbcoutinho/nextcloud-mcp-server:latest
+```
 
+See [Installation Guide](docs/installation.md) for detailed instructions.
 
-## Installation
+### 2. Configure
 
-### Prerequisites
+Create a `.env` file:
 
-*   Python 3.11+
-*   Access to a Nextcloud instance
-
-### Local Installation
-
-1.  Clone the repository (if running from source):
-    ```bash
-    git clone https://github.com/cbcoutinho/nextcloud-mcp-server.git
-    cd nextcloud-mcp-server
-    ```
-2.  Install the package dependencies (if running via CLI):
-    ```bash
-    uv sync
-    ```
-
-3.  Run the CLI --help command to see all available options
-    ```bash
-    $ uv run python -m nextcloud_mcp_server.app --help
-    Usage: python -m nextcloud_mcp_server.app [OPTIONS]
-
-    Options:
-      -h, --host TEXT                 [default: 127.0.0.1]
-      -p, --port INTEGER              [default: 8000]
-      -w, --workers INTEGER
-      -r, --reload
-      -l, --log-level [critical|error|warning|info|debug|trace]
-                                      [default: info]
-      -t, --transport [sse|streamable-http]
-                                      [default: sse]
-      -e, --enable-app [notes|tables|webdav|calendar|contacts|deck]
-                                      Enable specific Nextcloud app APIs. Can be
-                                      specified multiple times. If not specified,
-                                      all apps are enabled.
-      --help                          Show this message and exit.
-    ```
-
-### Docker
-
-A pre-built Docker image is available: `ghcr.io/cbcoutinho/nextcloud-mcp-server`
-
-## Configuration
-
-The server requires credentials to connect to your Nextcloud instance. Create a file named `.env` (or any name you prefer) in the directory where you'll run the server, based on the `env.sample` file:
+```bash
+# Copy the sample
+cp env.sample .env
+```
 
+**For OAuth (recommended):**
 ```dotenv
-# .env
 NEXTCLOUD_HOST=https://your.nextcloud.instance.com
-NEXTCLOUD_USERNAME=your_nextcloud_username
-NEXTCLOUD_PASSWORD=your_nextcloud_app_password_or_login_password
 ```
 
-*   `NEXTCLOUD_HOST`: The full URL of your Nextcloud instance.
-*   `NEXTCLOUD_USERNAME`: Your Nextcloud username.
-*   `NEXTCLOUD_PASSWORD`: **Important:** It is highly recommended to use a dedicated Nextcloud App Password for security. You can generate one in your Nextcloud Security settings. Alternatively, you can use your regular login password, but this is less secure.
-
-## Transport Types
-
-The server supports two transport types for MCP communication:
-
-### Streamable HTTP (Recommended)
-The `streamable-http` transport is the recommended and modern transport type that provides improved streaming capabilities:
-
-```bash
-# Use streamable-http transport (recommended)
-uv run python -m nextcloud_mcp_server.app --transport streamable-http
+**For Basic Auth:**
+```dotenv
+NEXTCLOUD_HOST=https://your.nextcloud.instance.com
+NEXTCLOUD_USERNAME=your_username
+NEXTCLOUD_PASSWORD=your_app_password
 ```
 
-### SSE (Server-Sent Events) - Deprecated
-> [!WARNING]
-> ⚠️ **Deprecated**: SSE transport is deprecated and will be removed in a future version of the MCP spec. SSE will be supported for the foreseable future, but users are encouraged to switch to the new transport type. Please migrate to `streamable-http`.
+See [Configuration Guide](docs/configuration.md) for all options.
+
+### 3. Set Up Authentication
+
+**OAuth Setup (recommended):**
+1. Install Nextcloud OIDC apps (`oidc` + `user_oidc`)
+2. Enable dynamic client registration
+3. Configure Bearer token validation
+4. Start the server
+
+See [OAuth Quick Start](docs/quickstart-oauth.md) for 5-minute setup or [OAuth Setup Guide](docs/oauth-setup.md) for production deployment.
+
+### 4. Run the Server
 
 ```bash
-# SSE transport (deprecated - for backwards compatibility only)
-uv run python -m nextcloud_mcp_server.app --transport sse
-```
-
-#### Docker Usage with Transports
-
-```bash
-# Using SSE transport (default - deprecated)
-docker run -p 127.0.0.1:8000:8000 --env-file .env --rm ghcr.io/cbcoutinho/nextcloud-mcp-server:latest
-
-# Using streamable-http transport (recommended)
-docker run -p 127.0.0.1:8000:8000 --env-file .env --rm ghcr.io/cbcoutinho/nextcloud-mcp-server:latest \
-  --transport streamable-http
-```
-
-**Note:** When using MCP clients, ensure your client supports the transport type you've configured on the server. Most modern MCP clients support streamable-http.
-
-## Running the Server
-
-### Locally
-
-Ensure your environment variables are loaded, then run the server. You have several options:
-
-#### Option 1: Using `nextcloud_mcp_server` cli (recommended)
-```bash
-# Load environment variables from your .env file
+# Load environment variables
 export $(grep -v '^#' .env | xargs)
 
-# Run the app module directly with custom options
-uv run python -m nextcloud_mcp_server.app --host 0.0.0.0 --port 8080 --log-level info
+# Start the server
+uv run nextcloud-mcp-server --oauth
 
-# Enable only specific Nextcloud app APIs
-uv run python -m nextcloud_mcp_server.app --enable-app notes --enable-app calendar
-
-# Enable only WebDAV for file operations
-uv run python -m nextcloud_mcp_server.app --enable-app webdav
+# Or with Docker
+docker run -p 127.0.0.1:8000:8000 --env-file .env --rm \
+  ghcr.io/cbcoutinho/nextcloud-mcp-server:latest --oauth
 ```
 
-#### Option 2: Using `uvicorn`
+The server starts on `http://127.0.0.1:8000` by default.
 
-You can also run the MCP server with `uvicorn` directly, which enables support
-for all uvicorn arguments (e.g. `--reload`, `--workers`).
+See [Running the Server](docs/running.md) for more options.
 
-```bash
-# Load environment variables from your .env file
-export $(grep -v '^#' .env | xargs)
+### 5. Connect an MCP Client
 
-# Run with uvicorn using the --factory option
-uv run uvicorn nextcloud_mcp_server.app:get_app --factory --reload --host 127.0.0.1 --port 8000
-```
-
-The server will start, typically listening on `http://127.0.0.1:8000`.
-
-**Host binding options:**
-- Use `--host 0.0.0.0` to bind to all interfaces
-- Use `--host 127.0.0.1` to bind only to localhost (default)
-
-See the full list of available `uvicorn` options and how to set them at [https://www.uvicorn.org/settings/]()
-
-### Selective App Enablement
-
-By default, all supported Nextcloud app APIs are enabled. You can selectively enable only specific apps using the `--enable-app` option:
-
-```bash
-# Available apps: notes, tables, webdav, calendar, contacts, deck
-
-# Enable all apps (default behavior)
-uv run python -m nextcloud_mcp_server.app
-
-# Enable only Notes and Calendar
-uv run python -m nextcloud_mcp_server.app --enable-app notes --enable-app calendar
-
-# Enable only WebDAV for file operations
-uv run python -m nextcloud_mcp_server.app --enable-app webdav
-
-# Enable multiple apps by repeating the option
-uv run python -m nextcloud_mcp_server.app --enable-app notes --enable-app tables --enable-app contacts
-```
-
-This can be useful for:
-- Reducing memory usage and startup time
-- Limiting available functionality for security or organizational reasons
-- Testing specific app integrations
-- Running lightweight instances with only needed features
-
-### Using Docker
-
-Mount your environment file when running the container:
-
-```bash
-# Run with all apps enabled (default)
-docker run -p 127.0.0.1:8000:8000 --env-file .env --rm ghcr.io/cbcoutinho/nextcloud-mcp-server:latest
-
-# Run with only specific apps enabled
-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 calendar
-
-# Run with only WebDAV
-docker run -p 127.0.0.1:8000:8000 --env-file .env --rm ghcr.io/cbcoutinho/nextcloud-mcp-server:latest \
-  --enable-app webdav
-```
-
-This will start the server and expose it on port 8000 of your local machine.
-
-## Usage
-
-Once the server is running, you can connect to it using an MCP client like `MCP Inspector`. Once your MCP server is running, launch MCP Inspector as follows:
+Test with MCP Inspector:
 
 ```bash
 uv run mcp dev
 ```
 
-You can then connect to and interact with the server's tools and resources through your browser.
+Or connect from:
+- Claude Desktop
+- Any MCP-compatible client
 
-## References:
+## Documentation
 
-- https://github.com/modelcontextprotocol/python-sdk
+### 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
+
+### OAuth Documentation
+- **[OAuth Quick Start](docs/quickstart-oauth.md)** - 5-minute setup guide
+- **[OAuth Setup Guide](docs/oauth-setup.md)** - Production deployment
+- **[OAuth Architecture](docs/oauth-architecture.md)** - How OAuth works
+- **[OAuth Troubleshooting](docs/oauth-troubleshooting.md)** - OAuth-specific issues
+- **[Upstream Status](docs/oauth-upstream-status.md)** - Required patches and PRs
+
+### Reference
+- **[Troubleshooting](docs/troubleshooting.md)** - Common issues and solutions
+
+### App-Specific Documentation
+- [Notes API](docs/notes.md)
+- [Calendar (CalDAV)](docs/calendar.md)
+- [Contacts (CardDAV)](docs/contacts.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
+Tools enable AI assistants to perform actions:
+- `nc_notes_create_note` - Create a new note
+- `deck_create_card` - Create a Deck card
+- `nc_calendar_create_event` - Create a calendar event
+- `nc_contacts_create_contact` - Create a contact
+- And many more...
+
+### Resources
+Resources provide read-only access to Nextcloud data:
+- `nc://capabilities` - Server capabilities
+- `nc://Deck/boards/{board_id}` - Deck board data
+- `notes://settings` - Notes app settings
+- And more...
+
+Run `uv run nextcloud-mcp-server --help` to see all available options.
+
+## Examples
+
+### Create a Note
+```
+AI: "Create a note called 'Meeting Notes' with today's agenda"
+→ Uses nc_notes_create_note tool
+```
+
+### Manage Calendar
+```
+AI: "Schedule a team meeting for next Tuesday at 2pm"
+→ Uses nc_calendar_create_event tool
+```
+
+### Organize Files
+```
+AI: "Create a folder called 'Project X' and move all PDFs there"
+→ Uses WebDAV tools (nc_webdav_create_directory, nc_webdav_move)
+```
+
+### Project Management
+```
+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
+```
+
+## Transport Protocols
+
+The server supports multiple MCP transport protocols:
+
+- **streamable-http** (recommended) - Modern streaming protocol
+- **sse** (default, deprecated) - Server-Sent Events for backward compatibility
+- **http** - Standard HTTP protocol
+
+```bash
+# Use streamable-http (recommended)
+uv run nextcloud-mcp-server --transport streamable-http
+```
+
+> [!WARNING]
+> SSE transport is deprecated and will be removed in a future MCP specification version. Please migrate to `streamable-http`.
 
 ## Contributing
 
-Contributions are welcome! Please feel free to submit issues or pull requests on the [GitHub repository](https://github.com/cbcoutinho/nextcloud-mcp-server).
+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
+
+## 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 for secure authentication
+- No credential storage with OAuth mode
+- Per-user access tokens
+- Regular security assessments
+
+Found a security issue? Please report it privately to the maintainers.
 
 ## License
 
-This project is licensed under the AGPL-3.0 License. See the [LICENSE](./LICENSE) file for details.
+This project is licensed under the AGPL-3.0 License. See [LICENSE](./LICENSE) for details.
 
-[![MseeP.ai Security Assessment Badge](https://mseep.net/pr/cbcoutinho-nextcloud-mcp-server-badge.png)](https://mseep.ai/app/cbcoutinho-nextcloud-mcp-server)
+## Star History
+
+[![Star History Chart](https://api.star-history.com/svg?repos=cbcoutinho/nextcloud-mcp-server&type=Date)](https://www.star-history.com/#cbcoutinho/nextcloud-mcp-server&Date)
+
+## References
+
+- [Model Context Protocol](https://github.com/modelcontextprotocol)
+- [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk)
+- [Nextcloud](https://nextcloud.com/)

app-hooks/post-installation/0001-Fix-Bearer-token-authentication-causing-session-logo.patch

@@ -0,0 +1,69 @@
+From deab2dac3d73d25f20a95c18103f327ab48f837a Mon Sep 17 00:00:00 2001
+From: Chris Coutinho <chris@coutinho.io>
+Date: Sun, 12 Oct 2025 21:09:29 +0200
+Subject: [PATCH 1/1] Fix Bearer token authentication causing session logout
+
+When using Bearer token authentication with OIDC, API requests to
+endpoints with @CORS annotations (like Notes API) were failing with
+401 Unauthorized errors. This occurred because:
+
+1. Bearer token validation successfully authenticated the user
+2. A session was created for the authenticated user
+3. Nextcloud's CORSMiddleware detected the logged-in session but no
+   CSRF token, causing it to call session->logout()
+4. The logout invalidated the session, breaking the API request
+
+This fix sets the 'app_api' session flag during Bearer token
+authentication, which instructs CORSMiddleware to skip the CSRF check
+and logout logic. This is the same mechanism used by Nextcloud's
+AppAPI framework for external application authentication.
+
+The flag is set at all successful Bearer token authentication points:
+- Line 243: After OIDC Identity Provider validation
+- Line 310: After auto-provisioning with bearer provisioning
+- Line 315: After existing user authentication
+- Line 337: After LDAP user sync
+
+Fixes: Bearer token authentication for all Nextcloud APIs
+Tested-with: nextcloud-mcp-server integration tests
+Signed-off-by: Chris Coutinho <chris@coutinho.io>
+---
+ lib/User/Backend.php | 4 ++++
+ 1 file changed, 4 insertions(+)
+
+diff --git a/lib/User/Backend.php b/lib/User/Backend.php
+index 23cfb18..65665cc 100644
+--- a/lib/User/Backend.php
++++ b/lib/User/Backend.php
+@@ -240,6 +240,7 @@ class Backend extends ABackend implements IPasswordConfirmationBackend, IGetDisp
+ 					$this->eventDispatcher->dispatchTyped($validationEvent);
+ 					$oidcProviderUserId = $validationEvent->getUserId();
+ 					if ($oidcProviderUserId !== null) {
++						$this->session->set('app_api', true);
+ 						return $oidcProviderUserId;
+ 					} else {
+ 						$this->logger->debug('[NextcloudOidcProviderValidator] The bearer token validation has failed');
+@@ -306,10 +307,12 @@ class Backend extends ABackend implements IPasswordConfirmationBackend, IGetDisp
+ 							}
+ 
+ 							$this->session->set('last-password-confirm', strtotime('+4 year', time()));
++							$this->session->set('app_api', true);
+ 							return $userId;
+ 						} elseif ($this->userExists($tokenUserId)) {
+ 							$this->checkFirstLogin($tokenUserId);
+ 							$this->session->set('last-password-confirm', strtotime('+4 year', time()));
++							$this->session->set('app_api', true);
+ 							return $tokenUserId;
+ 						} else {
+ 							// check if the user exists locally
+@@ -331,6 +334,7 @@ class Backend extends ABackend implements IPasswordConfirmationBackend, IGetDisp
+ 							}
+ 							$this->checkFirstLogin($tokenUserId);
+ 							$this->session->set('last-password-confirm', strtotime('+4 year', time()));
++							$this->session->set('app_api', true);
+ 							return $tokenUserId;
+ 						}
+ 					}
+-- 
+2.51.0
+

app-hooks/post-installation/0002-Add-PKCE-code-challenge-methods-to-discovery-documen.patch

@@ -0,0 +1,16 @@
+diff --git a/lib/Util/DiscoveryGenerator.php b/lib/Util/DiscoveryGenerator.php
+index ee3cd57..6429f94 100644
+--- a/lib/Util/DiscoveryGenerator.php
++++ b/lib/Util/DiscoveryGenerator.php
+@@ -171,6 +171,11 @@ class DiscoveryGenerator
+             $discoveryPayload['registration_endpoint'] = $host . $this->urlGenerator->linkToRoute('oidc.DynamicRegistration.registerClient', []);
+         }
+ 
++        // Add PKCE support if enabled
++        if ($this->appConfig->getAppValueBool('proof_key_for_code_exchange', false)) {
++            $discoveryPayload['code_challenge_methods_supported'] = ['S256'];
++        }
++
+         $this->logger->info('Request to Discovery Endpoint.');
+ 
+         $response = new JSONResponse($discoveryPayload);

app-hooks/post-installation/install-calendar-app.sh

@@ -1,6 +1,6 @@
 #!/bin/bash
 
-set -e  # Exit on any error
+set -euox pipefail
 
 echo "Installing and configuring Calendar app..."
 

app-hooks/post-installation/install-contacts-app.sh

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

app-hooks/post-installation/install-deck-app.sh

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

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

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

app-hooks/post-installation/install-oidc-app.sh

@@ -0,0 +1,23 @@
+#!/bin/bash
+
+set -euox pipefail
+
+echo "Installing and configuring OIDC apps for testing..."
+
+# Enable the OIDC Identity Provider app
+php /var/www/html/occ app:enable oidc
+
+# Enable the user_oidc app (OIDC client for bearer token validation)
+php /var/www/html/occ app:enable user_oidc
+
+patch -u /var/www/html/custom_apps/user_oidc/lib/User/Backend.php -i /docker-entrypoint-hooks.d/post-installation/0001-Fix-Bearer-token-authentication-causing-session-logo.patch
+patch -u /var/www/html/custom_apps/oidc/lib/Util/DiscoveryGenerator.php -i /docker-entrypoint-hooks.d/post-installation/0002-Add-PKCE-code-challenge-methods-to-discovery-documen.patch
+
+# Configure OIDC Identity Provider with dynamic client registration enabled
+php /var/www/html/occ config:app:set oidc dynamic_client_registration --value='true'
+php /var/www/html/occ config:app:set oidc proof_key_for_code_exchange --value=true --type=boolean
+
+# Configure user_oidc to validate bearer tokens from the OIDC Identity Provider
+php /var/www/html/occ config:system:set user_oidc oidc_provider_bearer_validation --value=true --type=boolean
+
+echo "OIDC apps installed and configured successfully"

app-hooks/post-installation/install-tables-app.sh

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

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: mariadb:lts@sha256:ec5d50f32359ff020b93cce6834f9bf89147c34aea0e90c952ccf556c94a4fb8
+    image: docker.io/library/mariadb:lts@sha256:ae6119716edac6998ae85508431b3d2e666530ddf4e94c61a10710caec9b0f71
     restart: always
     command: --transaction-isolation=READ-COMMITTED
     volumes:
@@ -17,18 +17,14 @@ services:
   # Note: Redis is an external service. You can find more information about the configuration here:
   # https://hub.docker.com/_/redis
   redis:
-    image: redis:alpine@sha256:987c376c727652f99625c7d205a1cba3cb2c53b92b0b62aade2bd48ee1593232
+    image: docker.io/library/redis:alpine@sha256:59b6e694653476de2c992937ebe1c64182af4728e54bb49e9b7a6c26614d8933
     restart: always
 
   app:
-    image: nextcloud:31.0.8@sha256:c3329db9d0d0d79b1fe6433b54b81c28acaefecfe96a400be202b7da80f6b8ca
-    #user: www-data:www-data
+    image: docker.io/library/nextcloud:32.0.0@sha256:3e70e4dfe882ef44738fdc30d9896fb07c12febb27c4a1177e3d63dc0004a0b4
     restart: always
-    #post_start:
-      #- command: chown -R www-data:www-data /var/www/html && while ! nc -z db 3306; do sleep 1; echo sleeping; done
-        #user: root
     ports:
-      - 127.0.0.1:8080:80
+      - 0.0.0.0:8080:80
     depends_on:
       - redis
       - db
@@ -47,15 +43,33 @@ services:
   mcp:
     build: .
     command: ["--transport", "streamable-http"]
+    restart: always
+    depends_on:
+      - app
     ports:
       - 127.0.0.1:8000:8000
     environment:
       - NEXTCLOUD_HOST=http://app:80
       - NEXTCLOUD_USERNAME=admin
       - NEXTCLOUD_PASSWORD=admin
-    #volumes:
-      #- ./nextcloud_mcp_server:/app/nextcloud_mcp_server:ro
+
+  mcp-oauth:
+    build: .
+    command: ["--transport", "streamable-http", "--oauth", "--port", "8001"]
+    restart: always
+    depends_on:
+      - app
+    ports:
+      - 127.0.0.1:8001:8001
+    environment:
+      - NEXTCLOUD_HOST=http://app:80
+      - NEXTCLOUD_MCP_SERVER_URL=http://127.0.0.1:8001
+      - NEXTCLOUD_PUBLIC_ISSUER_URL=http://127.0.0.1:8080
+      # No USERNAME/PASSWORD - will use OAuth
+    volumes:
+      - oauth-client-storage:/app/.oauth
 
 volumes:
   nextcloud:
   db:
+  oauth-client-storage:

docs/authentication.md

@@ -0,0 +1,161 @@
+# Authentication
+
+The Nextcloud MCP server supports two authentication modes for connecting to your Nextcloud instance.
+
+## Authentication Modes Comparison
+
+| Mode | Status | Security | Use Case |
+|------|--------|----------|----------|
+| **OAuth2/OIDC** | ✅ Recommended | 🔒 High | Production deployments, multi-user scenarios |
+| **Basic Auth** | ⚠️ Legacy | ⚠️ Lower | Development, backward compatibility |
+
+## OAuth2/OIDC (Recommended)
+
+OAuth2/OIDC authentication provides secure, token-based authentication following modern security standards.
+
+### Architecture
+
+The Nextcloud MCP Server acts as an **OAuth 2.0 Resource Server**, protecting access to Nextcloud resources:
+
+```
+MCP Client ←→ MCP Server (Resource Server) ←→ Nextcloud (Authorization Server + APIs)
+            OAuth Flow with PKCE            Bearer Token Auth
+```
+
+**Key Components**:
+- **MCP Server**: OAuth Resource Server (validates tokens, provides MCP tools)
+- **Nextcloud `oidc` app**: OAuth Authorization Server (issues tokens)
+- **Nextcloud `user_oidc` app**: Token validation middleware
+- **MCP Client**: Any MCP-compatible client (Claude, custom clients)
+
+For detailed architecture, see [OAuth Architecture](oauth-architecture.md).
+
+### Required Nextcloud Apps
+
+OAuth authentication requires **two Nextcloud apps** to work together:
+
+#### 1. `oidc` - OIDC Identity Provider
+**Purpose:** Makes Nextcloud an OAuth2/OIDC authorization server
+
+**Provides:**
+- OAuth2 authorization endpoint (`/apps/oidc/authorize`)
+- Token endpoint (`/apps/oidc/token`)
+- User info endpoint (`/apps/oidc/userinfo`)
+- JWKS endpoint for token validation (`/apps/oidc/jwks`)
+- Dynamic client registration endpoint (`/apps/oidc/register`)
+
+**Installation:** Available in Nextcloud App Store under "Security"
+
+#### 2. `user_oidc` - OpenID Connect User Backend
+**Purpose:** Authenticates users and validates Bearer tokens
+
+**Provides:**
+- Bearer token validation against the OIDC provider
+- User authentication via OIDC
+- Session management for authenticated users
+
+**Installation:** Available in Nextcloud App Store under "Security"
+
+**Important:** The `user_oidc` app requires a patch for Bearer token support on non-OCS endpoints (like Notes API). See [Upstream Status](oauth-upstream-status.md) for details.
+
+### Benefits
+- **Zero-config deployment** via dynamic client registration
+- **No credential storage** in environment variables
+- **Per-user authentication** with access tokens
+- **Per-user permissions** - each user has their own Nextcloud client
+- **Automatic token validation** via Nextcloud OIDC userinfo endpoint
+- **Token caching** for performance (default: 1 hour TTL)
+- **PKCE required** for enhanced security (S256 code challenge)
+- **Secure by design** following OAuth 2.0 and OpenID Connect standards
+
+### Current Implementation Limitations
+
+> [!IMPORTANT]
+> **Tested Configuration:**
+> - ✅ Nextcloud `oidc` app (OIDC Identity Provider) + `user_oidc` app (OIDC User Backend)
+> - ✅ Nextcloud acting as its own identity provider (self-hosted OIDC)
+> - ✅ MCP server as OAuth Resource Server
+> - ✅ PKCE with S256 code challenge method
+>
+> **Not Tested:**
+> - ❌ External identity providers (Azure AD, Keycloak, Okta, etc.)
+> - ❌ Using `user_oidc` with external OIDC providers
+>
+> **Known Requirements:**
+> - 🔧 The `user_oidc` app requires a patch for Bearer token support on non-OCS endpoints (see [Upstream Status](oauth-upstream-status.md))
+> - ⏱️ Dynamic client registration credentials expire (default: 1 hour) - use pre-configured clients for production
+> - 🔐 PKCE must be advertised in OIDC discovery (see [Upstream Status](oauth-upstream-status.md))
+
+### How OAuth Works
+
+The MCP server implements the OAuth 2.0 Resource Server pattern:
+
+**Phase 1: Authorization (OAuth Flow with PKCE)**
+1. MCP client connects and receives OAuth settings (issuer URL, scopes)
+2. Client initiates OAuth flow with PKCE (Proof Key for Code Exchange)
+3. User authenticates via browser to Nextcloud
+4. Nextcloud redirects back with authorization code
+5. Client exchanges code + code_verifier for access token
+
+**Phase 2: API Access (Bearer Token Validation)**
+6. Client sends MCP requests with `Authorization: Bearer <token>` header
+7. MCP server validates token by calling Nextcloud's userinfo endpoint
+8. Server creates per-user NextcloudClient instance with the token
+9. All Nextcloud API requests use the user's Bearer token
+10. User-specific permissions and audit trails apply
+
+This ensures:
+- Each user has their own authenticated session
+- Actions appear from the correct user in Nextcloud logs
+- Proper permission boundaries are maintained
+- No shared credentials between users
+
+### See Also
+- [OAuth Quick Start](quickstart-oauth.md) - 5-minute setup for development
+- [OAuth Setup Guide](oauth-setup.md) - Detailed production setup
+- [OAuth Architecture](oauth-architecture.md) - Technical details
+- [Upstream Status](oauth-upstream-status.md) - Required patches and PR status
+- [OAuth Troubleshooting](oauth-troubleshooting.md) - OAuth-specific issues
+- [Configuration](configuration.md) - Environment variables
+
+## Basic Authentication (Legacy)
+
+Basic Authentication uses username and password credentials directly.
+
+### Benefits
+- **Simple setup** with username/password
+- **Single-user** server instances
+- **Quick for development** and testing
+
+### Limitations
+- **Credentials in environment** (less secure)
+- **Single user only** - all requests use the same account
+- **No audit trail** - all actions appear from the same user
+- **Maintained for compatibility** - will be deprecated in future versions
+
+> [!WARNING]
+> **Security Notice:** Basic Authentication stores credentials in environment variables and is less secure than OAuth. It's maintained for backward compatibility only and may be deprecated in future versions. Use OAuth for production deployments.
+
+### See Also
+- [Configuration](configuration.md#basic-authentication-legacy) - BasicAuth environment variables
+- [Running the Server](running.md#basicauth-mode-legacy) - BasicAuth examples
+
+## Mode Detection
+
+The server automatically detects the authentication mode:
+
+- **OAuth mode**: When `NEXTCLOUD_USERNAME` and `NEXTCLOUD_PASSWORD` are NOT set
+- **BasicAuth mode**: When both username and password are provided
+
+You can also force a specific mode using CLI flags:
+```bash
+# Force OAuth mode
+uv run nextcloud-mcp-server --oauth
+
+# Force BasicAuth mode
+uv run nextcloud-mcp-server --no-oauth
+```
+
+## Switching Between Modes
+
+See [Troubleshooting: Switching Between OAuth and BasicAuth](troubleshooting.md#switching-between-oauth-and-basicauth) for instructions.

docs/configuration.md

@@ -0,0 +1,253 @@
+# Configuration
+
+The Nextcloud MCP server requires configuration to connect to your Nextcloud instance. Configuration is provided through environment variables, typically stored in a `.env` file.
+
+## Quick Start
+
+Create a `.env` file based on `env.sample`:
+
+```bash
+cp env.sample .env
+# Edit .env with your Nextcloud details
+```
+
+Then choose your authentication mode:
+
+- [OAuth2/OIDC Configuration](#oauth2oidc-configuration) (Recommended)
+- [Basic Authentication Configuration](#basic-authentication-legacy)
+
+---
+
+## OAuth2/OIDC Configuration
+
+OAuth2/OIDC is the recommended authentication mode for production deployments.
+
+### Minimal Configuration (Auto-registration)
+
+```dotenv
+# .env file for OAuth with auto-registration
+NEXTCLOUD_HOST=https://your.nextcloud.instance.com
+
+# Leave these EMPTY for OAuth mode
+NEXTCLOUD_USERNAME=
+NEXTCLOUD_PASSWORD=
+```
+
+This minimal configuration uses dynamic client registration to automatically register an OAuth client at startup.
+
+### Full Configuration (Pre-configured Client)
+
+```dotenv
+# .env file for OAuth with pre-configured client
+NEXTCLOUD_HOST=https://your.nextcloud.instance.com
+
+# OAuth Client Credentials (optional - auto-registers if not provided)
+NEXTCLOUD_OIDC_CLIENT_ID=your-client-id
+NEXTCLOUD_OIDC_CLIENT_SECRET=your-client-secret
+
+# OAuth Storage and Callback Settings (optional)
+NEXTCLOUD_OIDC_CLIENT_STORAGE=.nextcloud_oauth_client.json
+NEXTCLOUD_MCP_SERVER_URL=http://localhost:8000
+
+# Leave these EMPTY for OAuth mode
+NEXTCLOUD_USERNAME=
+NEXTCLOUD_PASSWORD=
+```
+
+### Environment Variables Reference
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `NEXTCLOUD_HOST` | ✅ Yes | - | Full URL of your Nextcloud instance (e.g., `https://cloud.example.com`) |
+| `NEXTCLOUD_OIDC_CLIENT_ID` | ⚠️ Optional | - | OAuth client ID (auto-registers if empty) |
+| `NEXTCLOUD_OIDC_CLIENT_SECRET` | ⚠️ Optional | - | OAuth client secret (auto-registers if empty) |
+| `NEXTCLOUD_OIDC_CLIENT_STORAGE` | ⚠️ Optional | `.nextcloud_oauth_client.json` | Path to store auto-registered client credentials |
+| `NEXTCLOUD_MCP_SERVER_URL` | ⚠️ Optional | `http://localhost:8000` | MCP server URL for OAuth callbacks |
+| `NEXTCLOUD_USERNAME` | ❌ Must be empty | - | Leave empty to enable OAuth mode |
+| `NEXTCLOUD_PASSWORD` | ❌ Must be empty | - | Leave empty to enable OAuth mode |
+
+### Prerequisites
+
+Before using OAuth configuration:
+
+1. **Install required Nextcloud apps** (both are required):
+   - **`oidc`** - OIDC Identity Provider (Apps → Security)
+   - **`user_oidc`** - OpenID Connect user backend (Apps → Security)
+
+2. **Configure the apps**:
+   - Enable dynamic client registration (if using auto-registration) - Settings → OIDC
+   - Enable Bearer token validation: `php occ config:system:set user_oidc oidc_provider_bearer_validation --value=true --type=boolean`
+
+3. **Apply Bearer token patch** - The `user_oidc` app requires a patch for non-OCS endpoints - See [Upstream Status](oauth-upstream-status.md) for details
+
+See the [OAuth Setup Guide](oauth-setup.md) for detailed step-by-step instructions, or [OAuth Quick Start](quickstart-oauth.md) for a 5-minute setup.
+
+---
+
+## Basic Authentication (Legacy)
+
+Basic Authentication is maintained for backward compatibility. It uses username and password credentials.
+
+> [!WARNING]
+> **Security Notice:** Basic Authentication stores credentials in environment variables and is less secure than OAuth. Use OAuth for production deployments.
+
+### Configuration
+
+```dotenv
+# .env file for BasicAuth mode
+NEXTCLOUD_HOST=https://your.nextcloud.instance.com
+NEXTCLOUD_USERNAME=your_nextcloud_username
+NEXTCLOUD_PASSWORD=your_app_password_or_password
+```
+
+### Environment Variables Reference
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `NEXTCLOUD_HOST` | ✅ Yes | Full URL of your Nextcloud instance |
+| `NEXTCLOUD_USERNAME` | ✅ Yes | Your Nextcloud username |
+| `NEXTCLOUD_PASSWORD` | ✅ Yes | **Recommended:** Use a dedicated [Nextcloud App Password](https://docs.nextcloud.com/server/latest/user_manual/en/session_management.html#managing-devices). Generate one in Nextcloud Security settings. Alternatively, use your login password (less secure). |
+
+---
+
+## Loading Environment Variables
+
+After creating your `.env` file, load the environment variables:
+
+### On Linux/macOS
+
+```bash
+# Load all variables from .env
+export $(grep -v '^#' .env | xargs)
+```
+
+### On Windows (PowerShell)
+
+```powershell
+# Load variables from .env
+Get-Content .env | ForEach-Object {
+    if ($_ -match '^\s*([^#][^=]*)\s*=\s*(.*)$') {
+        [Environment]::SetEnvironmentVariable($matches[1].Trim(), $matches[2].Trim(), "Process")
+    }
+}
+```
+
+### Via Docker
+
+```bash
+# Docker automatically loads .env when using --env-file
+docker run -p 127.0.0.1:8000:8000 --env-file .env --rm \
+  ghcr.io/cbcoutinho/nextcloud-mcp-server:latest
+```
+
+---
+
+## CLI Configuration
+
+Some configuration options can also be provided via CLI arguments. CLI arguments take precedence over environment variables.
+
+### OAuth-related CLI Options
+
+```bash
+uv run nextcloud-mcp-server --help
+
+Options:
+  --oauth / --no-oauth            Force OAuth mode (if enabled) or
+                                  BasicAuth mode (if disabled). By default,
+                                  auto-detected based on environment
+                                  variables.
+  --oauth-client-id TEXT          OAuth client ID (can also use
+                                  NEXTCLOUD_OIDC_CLIENT_ID env var)
+  --oauth-client-secret TEXT      OAuth client secret (can also use
+                                  NEXTCLOUD_OIDC_CLIENT_SECRET env var)
+  --oauth-storage-path TEXT       Path to store OAuth client credentials
+                                  (can also use
+                                  NEXTCLOUD_OIDC_CLIENT_STORAGE env var)
+                                  [default: .nextcloud_oauth_client.json]
+  --mcp-server-url TEXT           MCP server URL for OAuth callbacks (can
+                                  also use NEXTCLOUD_MCP_SERVER_URL env
+                                  var)  [default: http://localhost:8000]
+```
+
+### Server Options
+
+```bash
+Options:
+  -h, --host TEXT                 Server host  [default: 127.0.0.1]
+  -p, --port INTEGER              Server port  [default: 8000]
+  -w, --workers INTEGER           Number of worker processes
+  -r, --reload                    Enable auto-reload
+  -l, --log-level [critical|error|warning|info|debug|trace]
+                                  Logging level  [default: info]
+  -t, --transport [sse|streamable-http|http]
+                                  MCP transport protocol  [default: sse]
+```
+
+### App Selection
+
+```bash
+Options:
+  -e, --enable-app [notes|tables|webdav|calendar|contacts|deck]
+                                  Enable specific Nextcloud app APIs. Can
+                                  be specified multiple times. If not
+                                  specified, all apps are enabled.
+```
+
+### Example CLI Usage
+
+```bash
+# OAuth mode with custom client and port
+uv run nextcloud-mcp-server --oauth \
+  --oauth-client-id abc123 \
+  --oauth-client-secret xyz789 \
+  --port 8080
+
+# BasicAuth mode with specific apps only
+uv run nextcloud-mcp-server --no-oauth \
+  --enable-app notes \
+  --enable-app calendar
+```
+
+---
+
+## Configuration Best Practices
+
+### For Development
+
+- Use BasicAuth for quick setup and testing
+- Or use OAuth with auto-registration (dynamic client registration)
+- Store `.env` file in your project directory
+- Add `.env` to `.gitignore`
+
+### For Production
+
+- **Always use OAuth2/OIDC** with pre-configured clients
+- Store OAuth client credentials securely
+- Use environment variables from your deployment platform (Docker secrets, Kubernetes ConfigMaps, etc.)
+- Never commit credentials to version control
+- Set appropriate file permissions on credential storage:
+  ```bash
+  chmod 600 .nextcloud_oauth_client.json
+  ```
+
+### For Docker
+
+- Mount OAuth client storage as a volume for persistence:
+  ```bash
+  docker run -v $(pwd)/.oauth:/app/.oauth --env-file .env \
+    ghcr.io/cbcoutinho/nextcloud-mcp-server:latest
+  ```
+- Use Docker secrets for sensitive values in production
+
+---
+
+## See Also
+
+- [OAuth Quick Start](quickstart-oauth.md) - 5-minute OAuth setup for development
+- [OAuth Setup Guide](oauth-setup.md) - Detailed OAuth configuration for production
+- [OAuth Architecture](oauth-architecture.md) - How OAuth works in the MCP server
+- [Upstream Status](oauth-upstream-status.md) - Required patches and upstream PRs
+- [Authentication](authentication.md) - Authentication modes comparison
+- [Running the Server](running.md) - Starting the server with different configurations
+- [Troubleshooting](troubleshooting.md) - Common configuration issues
+- [OAuth Troubleshooting](oauth-troubleshooting.md) - OAuth-specific troubleshooting

docs/installation.md

@@ -0,0 +1,215 @@
+# Installation
+
+This guide covers installing the Nextcloud MCP server on your system.
+
+## Prerequisites
+
+- **Python 3.11+** - Check with `python3 --version`
+- **Access to a Nextcloud instance** - Self-hosted or cloud-hosted
+- **Administrator access** (for OAuth setup) - Required to install OIDC app
+
+## Installation Methods
+
+Choose one of the following installation methods:
+
+- [From Source (Recommended)](#from-source-recommended)
+- [Using Docker](#using-docker)
+
+---
+
+## From Source (Recommended)
+
+Install from the GitHub repository using uv or pip.
+
+### Prerequisites
+
+Install [uv](https://github.com/astral-sh/uv) (recommended) or ensure pip is available:
+
+```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"
+```
+
+### Clone the Repository
+
+```bash
+git clone https://github.com/cbcoutinho/nextcloud-mcp-server.git
+cd nextcloud-mcp-server
+```
+
+### Install Dependencies
+
+#### Using uv (Recommended)
+
+```bash
+# Install dependencies
+uv sync
+
+# Install development dependencies (optional)
+uv sync --group dev
+```
+
+#### Using pip
+
+```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]"
+```
+
+### Verify Installation
+
+```bash
+# With uv
+uv run nextcloud-mcp-server --help
+
+# With pip/venv
+nextcloud-mcp-server --help
+```
+
+---
+
+## Using Docker
+
+A pre-built Docker image is available for easy deployment.
+
+### Pull the Image
+
+```bash
+docker pull ghcr.io/cbcoutinho/nextcloud-mcp-server:latest
+```
+
+### Run the Container
+
+```bash
+# Prepare your .env file first (see Configuration guide)
+
+# Run with environment file
+docker run -p 127.0.0.1:8000:8000 --env-file .env --rm \
+  ghcr.io/cbcoutinho/nextcloud-mcp-server:latest
+```
+
+### Docker Compose
+
+Create a `docker-compose.yml`:
+
+```yaml
+version: '3.8'
+
+services:
+  mcp:
+    image: ghcr.io/cbcoutinho/nextcloud-mcp-server:latest
+    ports:
+      - "127.0.0.1:8000:8000"
+    env_file:
+      - .env
+    volumes:
+      # For persistent OAuth client storage
+      - ./oauth-storage:/app/.oauth
+    restart: unless-stopped
+```
+
+Start the service:
+
+```bash
+docker-compose up -d
+```
+
+---
+
+## Next Steps
+
+After installation:
+
+1. **Configure the server** - See [Configuration Guide](configuration.md)
+2. **Set up authentication** - See [OAuth Setup Guide](oauth-setup.md) or [Authentication](authentication.md)
+3. **Run the server** - See [Running the Server](running.md)
+
+## Updating
+
+### Update from Source
+
+```bash
+cd nextcloud-mcp-server
+git pull origin master
+
+# Using uv
+uv sync
+
+# Or using pip
+pip install -e .
+```
+
+### Update Docker Image
+
+```bash
+docker pull ghcr.io/cbcoutinho/nextcloud-mcp-server:latest
+
+# If using docker-compose
+docker-compose up -d  # Restart with new image
+
+# If using docker run
+# Stop the old container and start a new one with the updated image
+```
+
+## Troubleshooting Installation
+
+### Issue: "Python version too old"
+
+**Cause:** Python 3.11+ is required.
+
+**Solution:**
+```bash
+# Check your Python version
+python3 --version
+
+# Install Python 3.11+ from:
+# - https://www.python.org/downloads/
+# - Or use your system package manager (apt, brew, etc.)
+```
+
+### Issue: "Command not found: nextcloud-mcp-server"
+
+**Cause:** The package is not in your PATH.
+
+**Solution:**
+```bash
+# Ensure your virtual environment is activated
+source venv/bin/activate
+
+# Or use uv run
+uv run nextcloud-mcp-server --help
+
+# Or use python -m
+python -m nextcloud_mcp_server.app --help
+```
+
+### Issue: Docker permission denied
+
+**Cause:** Docker requires elevated permissions.
+
+**Solution:**
+```bash
+# Add your user to the docker group (Linux)
+sudo usermod -aG docker $USER
+# Log out and back in
+
+# Or use sudo
+sudo docker run ...
+```
+
+## See Also
+
+- [Configuration Guide](configuration.md) - Environment variables and settings
+- [OAuth Setup Guide](oauth-setup.md) - OAuth authentication setup
+- [Running the Server](running.md) - Starting and managing the server

docs/oauth-architecture.md

@@ -0,0 +1,322 @@
+# OAuth Architecture
+
+This document explains how OAuth2/OIDC authentication works in the Nextcloud MCP Server implementation.
+
+## Overview
+
+The Nextcloud MCP Server acts as an **OAuth 2.0 Resource Server**, protecting access to Nextcloud resources. It relies on Nextcloud's OIDC Identity Provider for user authentication and token validation.
+
+## Architecture Diagram
+
+```
+┌─────────────┐                  ┌──────────────────┐                  ┌─────────────────┐
+│             │                  │                  │                  │                 │
+│ MCP Client  │                  │   MCP Server     │                  │   Nextcloud     │
+│ (Claude,    │                  │   (Resource      │                  │   Instance      │
+│  etc.)      │                  │    Server)       │                  │                 │
+│             │                  │                  │                  │                 │
+└──────┬──────┘                  └────────┬─────────┘                  └────────┬────────┘
+       │                                  │                                     │
+       │                                  │                                     │
+       │  1. Connect to MCP               │                                     │
+       ├─────────────────────────────────>│                                     │
+       │                                  │                                     │
+       │  2. Return auth settings         │                                     │
+       │     (issuer_url, scopes)         │                                     │
+       │<─────────────────────────────────┤                                     │
+       │                                  │                                     │
+       │                                  │                                     │
+       │  3. Start OAuth flow (with PKCE) │                                     │
+       ├──────────────────────────────────┼────────────────────────────────────>│
+       │                                  │   /apps/oidc/authorize              │
+       │                                  │                                     │
+       │  4. User authenticates in browser│                                     │
+       │<─────────────────────────────────┼─────────────────────────────────────┤
+       │                                  │                                     │
+       │  5. Authorization code (redirect)│                                     │
+       │<─────────────────────────────────┤                                     │
+       │                                  │                                     │
+       │  6. Exchange code for token      │                                     │
+       ├──────────────────────────────────┼────────────────────────────────────>│
+       │                                  │   /apps/oidc/token                  │
+       │                                  │                                     │
+       │  7. Access token                 │                                     │
+       │<─────────────────────────────────┼─────────────────────────────────────┤
+       │                                  │                                     │
+       │                                  │                                     │
+       │  8. API request with Bearer token│                                     │
+       ├─────────────────────────────────>│                                     │
+       │     Authorization: Bearer xxx    │                                     │
+       │                                  │                                     │
+       │                                  │  9. Validate token via userinfo     │
+       │                                  ├────────────────────────────────────>│
+       │                                  │     /apps/oidc/userinfo             │
+       │                                  │                                     │
+       │                                  │  10. User info (token valid)        │
+       │                                  │<────────────────────────────────────┤
+       │                                  │                                     │
+       │                                  │  11. Nextcloud API request          │
+       │                                  ├────────────────────────────────────>│
+       │                                  │     Authorization: Bearer xxx       │
+       │                                  │     (Notes, Calendar, etc.)         │
+       │                                  │                                     │
+       │                                  │  12. API response                   │
+       │                                  │<────────────────────────────────────┤
+       │                                  │                                     │
+       │  13. MCP tool response           │                                     │
+       │<─────────────────────────────────┤                                     │
+       │                                  │                                     │
+```
+
+## Components
+
+### 1. MCP Client
+- Any MCP-compatible client (Claude Desktop, Claude Code, custom clients)
+- Initiates OAuth flow with PKCE (Proof Key for Code Exchange)
+- Stores and sends access token with each request
+- **Example**: Claude Desktop, Claude Code
+
+### 2. MCP Server (Resource Server)
+- **Role**: OAuth 2.0 Resource Server
+- **Location**: This Nextcloud MCP Server implementation
+- **Responsibilities**:
+  - Validates Bearer tokens by calling Nextcloud's userinfo endpoint
+  - Caches validated tokens (default: 1 hour TTL)
+  - Creates authenticated Nextcloud client instances per-user
+  - Enforces PKCE requirements (S256 code challenge method)
+  - Exposes Nextcloud functionality via MCP tools
+
+**Key Files**:
+- [`app.py`](../nextcloud_mcp_server/app.py) - OAuth mode detection and configuration
+- [`auth/token_verifier.py`](../nextcloud_mcp_server/auth/token_verifier.py) - Token validation logic
+- [`auth/context_helper.py`](../nextcloud_mcp_server/auth/context_helper.py) - Per-user client creation
+
+### 3. Nextcloud OIDC Apps
+
+#### a) `oidc` - OIDC Identity Provider
+- **Role**: OAuth 2.0 Authorization Server
+- **Location**: Nextcloud app (`apps/oidc`)
+- **Endpoints**:
+  - `/.well-known/openid-configuration` - Discovery endpoint
+  - `/apps/oidc/authorize` - Authorization endpoint
+  - `/apps/oidc/token` - Token endpoint
+  - `/apps/oidc/userinfo` - User info endpoint (token validation)
+  - `/apps/oidc/jwks` - JSON Web Key Set
+  - `/apps/oidc/register` - Dynamic client registration
+
+**Configuration**:
+```bash
+# Enable dynamic client registration (optional)
+# Settings → OIDC → "Allow dynamic client registration"
+```
+
+#### b) `user_oidc` - OpenID Connect User Backend
+- **Role**: Bearer token validation middleware
+- **Location**: Nextcloud app (`apps/user_oidc`)
+- **Responsibilities**:
+  - Validates Bearer tokens for Nextcloud API requests
+  - Creates user sessions from valid Bearer tokens
+  - Integrates with Nextcloud's authentication system
+
+**Configuration**:
+```bash
+# Enable Bearer token validation (required)
+php occ config:system:set user_oidc oidc_provider_bearer_validation --value=true --type=boolean
+```
+
+> [!IMPORTANT]
+> The `user_oidc` app requires a patch to properly support Bearer token authentication for non-OCS endpoints. See [Upstream Status](oauth-upstream-status.md) for details.
+
+### 4. Nextcloud Instance
+- **Role**: Resource Owner / API Provider
+- **Provides**: Notes, Calendar, Contacts, Deck, Files, etc.
+
+## Authentication Flow
+
+### Phase 1: OAuth Authorization (Steps 1-7)
+
+1. **Client Connects**: MCP client connects to MCP server
+2. **Auth Settings**: MCP server returns OAuth settings:
+   ```json
+   {
+     "issuer_url": "https://nextcloud.example.com",
+     "resource_server_url": "http://localhost:8000",
+     "required_scopes": ["openid", "profile"]
+   }
+   ```
+3. **OAuth Flow**: Client initiates OAuth flow with PKCE
+   - Generates `code_verifier` (random string)
+   - Calculates `code_challenge` = SHA256(code_verifier)
+   - Redirects user to `/apps/oidc/authorize` with `code_challenge`
+4. **User Authentication**: User logs in to Nextcloud via browser
+5. **Authorization Code**: Nextcloud redirects back with authorization code
+6. **Token Exchange**: Client exchanges code for access token
+   - Sends `code` + `code_verifier` to `/apps/oidc/token`
+   - OIDC app validates PKCE challenge
+7. **Access Token**: Client receives access token (JWT or opaque)
+
+### Phase 2: API Access (Steps 8-13)
+
+8. **API Request**: Client sends MCP request with Bearer token
+9. **Token Validation**: MCP server validates token:
+   - Checks cache (1-hour TTL by default)
+   - If not cached, calls `/apps/oidc/userinfo` with Bearer token
+   - Extracts username from `sub` or `preferred_username` claim
+10. **User Info**: Nextcloud returns user info if token is valid
+11. **Nextcloud API Call**: MCP server calls Nextcloud API on behalf of user
+    - Creates `NextcloudClient` instance with Bearer token
+    - User-specific permissions apply
+12. **API Response**: Nextcloud returns data
+13. **MCP Response**: MCP server returns formatted response to client
+
+## Token Validation
+
+The MCP server validates tokens using the **userinfo endpoint approach**:
+
+### Why Userinfo (vs JWT Validation)?
+
+**Advantages**:
+- Works with both JWT and opaque tokens
+- No need to manage JWKS rotation
+- Always up-to-date (respects token revocation)
+- Simpler implementation
+
+**Caching Strategy**:
+- Validated tokens cached for 1 hour (configurable)
+- Cache keyed by token string
+- Expired tokens re-validated automatically
+
+**Implementation**: See [`NextcloudTokenVerifier`](../nextcloud_mcp_server/auth/token_verifier.py)
+
+## PKCE Requirement
+
+The MCP server **requires** PKCE with S256 code challenge method:
+
+1. Server validates OIDC discovery advertises PKCE support
+2. Checks for `code_challenge_methods_supported` field
+3. Verifies `S256` is included in supported methods
+4. Logs error if PKCE not properly advertised
+
+**Why PKCE?**:
+- Required by MCP specification
+- Protects against authorization code interception
+- Essential for public clients (desktop apps, CLI tools)
+
+**Implementation**: See [`validate_pkce_support()`](../nextcloud_mcp_server/app.py#L31-L93)
+
+## Client Registration
+
+The MCP server supports two client registration modes:
+
+### Automatic Registration (Dynamic Client Registration)
+
+```bash
+# No client credentials needed
+NEXTCLOUD_HOST=https://nextcloud.example.com
+```
+
+**How it works**:
+1. Server checks `/.well-known/openid-configuration` for `registration_endpoint`
+2. Calls `/apps/oidc/register` to register new client
+3. Saves credentials to `.nextcloud_oauth_client.json`
+4. Re-registers if credentials expire
+
+**Best for**: Development, testing, short-lived deployments
+
+### Pre-configured Client
+
+```bash
+# Manual client registration via CLI
+php occ oidc:create --name="MCP Server" --type=confidential --redirect-uri="http://localhost:8000/oauth/callback"
+
+# Configure MCP server
+NEXTCLOUD_HOST=https://nextcloud.example.com
+NEXTCLOUD_OIDC_CLIENT_ID=abc123
+NEXTCLOUD_OIDC_CLIENT_SECRET=xyz789
+```
+
+**Best for**: Production, long-running deployments
+
+## Per-User Client Instances
+
+Each authenticated user gets their own `NextcloudClient` instance:
+
+```python
+# From MCP context (contains validated token)
+client = get_client_from_context(ctx)
+
+# Creates NextcloudClient with:
+# - username: from token's 'sub' or 'preferred_username' claim
+# - auth: BearerAuth(token)
+```
+
+**Benefits**:
+- User-specific permissions
+- Audit trail (actions appear from correct user)
+- No shared credentials
+- Multi-user support
+
+**Implementation**: See [`get_client_from_context()`](../nextcloud_mcp_server/auth/context_helper.py)
+
+## Security Considerations
+
+### Token Storage
+- MCP client stores access token
+- MCP server does NOT store tokens (validates per-request)
+- Token validation results cached in-memory only
+
+### PKCE Protection
+- Server validates PKCE is advertised
+- Client MUST use PKCE with S256
+- Protects against authorization code interception
+
+### Scopes
+- Required scopes: `openid`, `profile`
+- Additional scopes inferred from userinfo response
+
+### Token Validation
+- Every MCP request validates Bearer token
+- Cached for performance (1-hour default)
+- Calls userinfo endpoint for validation
+
+## Configuration
+
+See [Configuration Guide](configuration.md) for all OAuth environment variables:
+
+| Variable | Purpose |
+|----------|---------|
+| `NEXTCLOUD_HOST` | Nextcloud instance URL |
+| `NEXTCLOUD_OIDC_CLIENT_ID` | Pre-configured client ID (optional) |
+| `NEXTCLOUD_OIDC_CLIENT_SECRET` | Pre-configured client secret (optional) |
+| `NEXTCLOUD_MCP_SERVER_URL` | MCP server URL for OAuth callbacks |
+| `NEXTCLOUD_OIDC_CLIENT_STORAGE` | Path for auto-registered credentials |
+
+## Testing
+
+The integration test suite includes comprehensive OAuth testing:
+
+- **Automated tests** (Playwright): [`tests/integration/test_oauth_playwright.py`](../tests/integration/test_oauth_playwright.py)
+- **Interactive tests**: [`tests/integration/test_oauth_interactive.py`](../tests/integration/test_oauth_interactive.py)
+- **Fixtures**: [`tests/conftest.py`](../tests/conftest.py)
+
+Run OAuth tests:
+```bash
+# Start OAuth-enabled MCP server
+docker-compose up --build -d mcp-oauth
+
+# Run automated tests
+uv run pytest tests/integration/test_oauth_playwright.py --browser firefox -v
+
+# Run interactive tests (manual login)
+uv run pytest tests/integration/test_oauth_interactive.py -v
+```
+
+## See Also
+
+- [OAuth Setup Guide](oauth-setup.md) - Configuration steps
+- [OAuth Quick Start](quickstart-oauth.md) - Get started quickly
+- [Upstream Status](oauth-upstream-status.md) - Required upstream patches
+- [OAuth Troubleshooting](oauth-troubleshooting.md) - Common issues
+- [RFC 6749](https://www.rfc-editor.org/rfc/rfc6749) - OAuth 2.0 Authorization Framework
+- [RFC 7636](https://www.rfc-editor.org/rfc/rfc7636) - PKCE
+- [OpenID Connect Core 1.0](https://openid.net/specs/openid-connect-core-1_0.html)

docs/oauth-setup.md

@@ -0,0 +1,545 @@
+# OAuth Setup Guide
+
+This guide walks you through setting up OAuth2/OIDC authentication for the Nextcloud MCP server in production.
+
+> **Quick Start?** If you want a 5-minute setup for development, see [OAuth Quick Start](quickstart-oauth.md).
+
+## Table of Contents
+
+- [Prerequisites](#prerequisites)
+- [Architecture Overview](#architecture-overview)
+- [Step 1: Install Nextcloud Apps](#step-1-install-nextcloud-apps)
+- [Step 2: Configure OIDC Apps](#step-2-configure-oidc-apps)
+- [Step 3: Choose Deployment Mode](#step-3-choose-deployment-mode)
+- [Step 4: Configure MCP Server](#step-4-configure-mcp-server)
+- [Step 5: Start and Verify](#step-5-start-and-verify)
+- [Testing Authentication](#testing-authentication)
+- [Production Recommendations](#production-recommendations)
+
+## Prerequisites
+
+Before beginning, ensure you have:
+
+- **Nextcloud instance** with administrator access
+- **Nextcloud version** 28 or later
+- **SSH/CLI access** to Nextcloud server (for `occ` commands)
+- **Python 3.11+** installed on MCP server host
+- **MCP server installed** (see [Installation Guide](installation.md))
+
+## Architecture Overview
+
+The OAuth implementation uses the following components:
+
+```
+MCP Client ←→ MCP Server (Resource Server) ←→ Nextcloud (Authorization Server + APIs)
+            OAuth Flow                       Bearer Token Auth
+```
+
+**Key Roles**:
+- **MCP Server**: OAuth Resource Server (validates tokens, provides MCP tools)
+- **Nextcloud `oidc` app**: OAuth Authorization Server (issues tokens)
+- **Nextcloud `user_oidc` app**: Token validation middleware
+
+For detailed architecture, see [OAuth Architecture](oauth-architecture.md).
+
+## Step 1: Install Nextcloud Apps
+
+OAuth authentication requires **two Nextcloud apps** to work together.
+
+### Required Apps
+
+#### 1. `oidc` - OIDC Identity Provider
+
+**Purpose**: Makes Nextcloud an OAuth2/OIDC authorization server
+
+**Installation**:
+1. Open Nextcloud as administrator
+2. Navigate to **Apps** → **Security**
+3. Find **"OIDC"** (full name: "OIDC Identity Provider")
+4. Click **Enable** or **Download and enable**
+
+**Provides**:
+- OAuth2 authorization endpoint
+- Token endpoint
+- User info endpoint
+- JWKS endpoint
+- Dynamic client registration endpoint (optional)
+
+#### 2. `user_oidc` - OpenID Connect User Backend
+
+**Purpose**: Authenticates users and validates Bearer tokens
+
+**Installation**:
+1. In **Apps** → **Security**
+2. Find **"OpenID Connect user backend"** (app ID: `user_oidc`)
+3. Click **Enable** or **Download and enable**
+
+**Provides**:
+- Bearer token validation against OIDC provider
+- User authentication via OIDC
+- Session management for authenticated users
+
+> [!IMPORTANT]
+> **Upstream Patch Required**: The `user_oidc` app needs a patch for Bearer token support with app-specific APIs (Notes, Calendar, etc.). The patch is pending upstream review.
+>
+> **Status**: See [Upstream Status](oauth-upstream-status.md) for current PR status and workarounds.
+>
+> **Impact**: OCS APIs work without patch, but app-specific APIs require the patch.
+
+### Verify Installation
+
+```bash
+# Check both apps are installed and enabled
+php occ app:list | grep -E "oidc|user_oidc"
+
+# Expected output:
+#  - oidc: enabled
+#  - user_oidc: enabled
+```
+
+## Step 2: Configure OIDC Apps
+
+### Configure `oidc` App (Identity Provider)
+
+#### Option A: Dynamic Client Registration (Development)
+
+**Best for**: Development, testing, auto-registration
+
+1. Navigate to **Settings** → **OIDC** (Administration settings)
+2. Enable **"Allow dynamic client registration"**
+3. (Optional) Configure client expiration:
+   ```bash
+   # Default: 3600 seconds (1 hour)
+   php occ config:app:set oidc expire_time --value "86400"  # 24 hours
+   ```
+
+#### Option B: Pre-configured Clients (Production)
+
+**Best for**: Production, long-running deployments
+
+Skip the dynamic registration setting. You'll manually register clients via CLI in Step 3.
+
+### Configure `user_oidc` App (Token Validation)
+
+**Required**: Enable Bearer token validation:
+
+```bash
+# SSH into Nextcloud server
+php occ config:system:set user_oidc oidc_provider_bearer_validation --value=true --type=boolean
+```
+
+This tells `user_oidc` to validate Bearer tokens against Nextcloud's OIDC Identity Provider.
+
+### Verify OIDC Discovery
+
+Test that OIDC discovery endpoint is accessible:
+
+```bash
+curl https://your.nextcloud.instance.com/.well-known/openid-configuration | jq
+```
+
+Expected response:
+```json
+{
+  "issuer": "https://your.nextcloud.instance.com",
+  "authorization_endpoint": "https://your.nextcloud.instance.com/apps/oidc/authorize",
+  "token_endpoint": "https://your.nextcloud.instance.com/apps/oidc/token",
+  "userinfo_endpoint": "https://your.nextcloud.instance.com/apps/oidc/userinfo",
+  "jwks_uri": "https://your.nextcloud.instance.com/apps/oidc/jwks",
+  "registration_endpoint": "https://your.nextcloud.instance.com/apps/oidc/register",
+  ...
+}
+```
+
+### PKCE Support
+
+The MCP server **requires PKCE** (Proof Key for Code Exchange) with S256 code challenge method.
+
+**Validation**: The MCP server automatically validates PKCE support at startup by checking the discovery response for `code_challenge_methods_supported`.
+
+**Note**: If PKCE is not advertised in discovery metadata, the server logs a warning but continues (PKCE still works, it's just not advertised). See [Upstream Status](oauth-upstream-status.md) for tracking.
+
+## Step 3: Choose Deployment Mode
+
+You have two options for managing OAuth clients:
+
+### Mode A: Automatic Registration (Dynamic Client Registration)
+
+**Best for**: Development, testing, short-lived deployments
+
+**How it works**:
+- MCP server automatically registers OAuth client at startup
+- Uses Nextcloud's dynamic client registration endpoint
+- Saves credentials to `.nextcloud_oauth_client.json`
+- Re-registers automatically if credentials expire
+
+**Pros**:
+- Zero configuration required
+- Quick setup
+- No manual client management
+
+**Cons**:
+- Clients expire (default: 1 hour, configurable)
+- Must re-register on restart if expired
+- Not ideal for long-running production
+
+**Configuration**: Skip to [Step 4](#step-4-configure-mcp-server) with minimal config.
+
+---
+
+### Mode B: Pre-configured Client (Production)
+
+**Best for**: Production, long-running deployments, stable environments
+
+**How it works**:
+- You manually register OAuth client via Nextcloud CLI
+- Provide client credentials to MCP server
+- Credentials don't expire
+
+**Pros**:
+- Credentials don't expire
+- Stable for production
+- More control over client configuration
+- Better for audit trails
+
+**Cons**:
+- Requires manual setup
+- Needs SSH/CLI access to Nextcloud server
+
+**Setup**: Register a client via CLI:
+
+```bash
+# SSH into Nextcloud server
+php occ oidc:create \
+  --name="Nextcloud MCP Server" \
+  --type=confidential \
+  --redirect-uri="http://localhost:8000/oauth/callback"
+
+# Example output:
+# Client ID: abc123xyz789
+# Client Secret: secret456def012
+
+# Save these credentials for Step 4
+```
+
+**Important**: Adjust `--redirect-uri` to match your MCP server URL:
+- Local: `http://localhost:8000/oauth/callback`
+- Remote: `http://your-server:8000/oauth/callback`
+- Custom port: `http://your-server:PORT/oauth/callback`
+
+The redirect URI **must** be:
+```
+{NEXTCLOUD_MCP_SERVER_URL}/oauth/callback
+```
+
+## Step 4: Configure MCP Server
+
+Create or update your `.env` file with OAuth configuration.
+
+### For Mode A (Automatic Registration)
+
+```bash
+# Copy sample if needed
+cp env.sample .env
+
+# Edit .env
+cat > .env << 'EOF'
+# Nextcloud Instance
+NEXTCLOUD_HOST=https://your.nextcloud.instance.com
+
+# Leave EMPTY for OAuth mode (do not set USERNAME/PASSWORD)
+NEXTCLOUD_USERNAME=
+NEXTCLOUD_PASSWORD=
+
+# Optional: MCP server URL (for OAuth callbacks)
+NEXTCLOUD_MCP_SERVER_URL=http://localhost:8000
+
+# Optional: Client storage path
+NEXTCLOUD_OIDC_CLIENT_STORAGE=.nextcloud_oauth_client.json
+EOF
+```
+
+### For Mode B (Pre-configured Client)
+
+```bash
+# Copy sample if needed
+cp env.sample .env
+
+# Edit .env
+cat > .env << 'EOF'
+# Nextcloud Instance
+NEXTCLOUD_HOST=https://your.nextcloud.instance.com
+
+# OAuth Client Credentials (from Step 3)
+NEXTCLOUD_OIDC_CLIENT_ID=abc123xyz789
+NEXTCLOUD_OIDC_CLIENT_SECRET=secret456def012
+
+# MCP server URL (must match redirect URI)
+NEXTCLOUD_MCP_SERVER_URL=http://localhost:8000
+
+# Leave EMPTY for OAuth mode
+NEXTCLOUD_USERNAME=
+NEXTCLOUD_PASSWORD=
+EOF
+```
+
+### Environment Variables Reference
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `NEXTCLOUD_HOST` | ✅ Yes | - | Full URL of Nextcloud instance |
+| `NEXTCLOUD_OIDC_CLIENT_ID` | ⚠️ Mode B only | - | OAuth client ID |
+| `NEXTCLOUD_OIDC_CLIENT_SECRET` | ⚠️ Mode B only | - | OAuth client secret |
+| `NEXTCLOUD_MCP_SERVER_URL` | ⚠️ Optional | `http://localhost:8000` | MCP server URL for callbacks |
+| `NEXTCLOUD_OIDC_CLIENT_STORAGE` | ⚠️ Optional | `.nextcloud_oauth_client.json` | Client credentials storage path |
+| `NEXTCLOUD_USERNAME` | ❌ Must be empty | - | Leave empty for OAuth |
+| `NEXTCLOUD_PASSWORD` | ❌ Must be empty | - | Leave empty for OAuth |
+
+See [Configuration Guide](configuration.md) for all options.
+
+## Step 5: Start and Verify
+
+### Load Environment Variables
+
+```bash
+# Load from .env file
+export $(grep -v '^#' .env | xargs)
+
+# Verify key variables are set
+echo "NEXTCLOUD_HOST: $NEXTCLOUD_HOST"
+echo "NEXTCLOUD_MCP_SERVER_URL: $NEXTCLOUD_MCP_SERVER_URL"
+```
+
+### Start MCP Server
+
+```bash
+# Start with OAuth mode
+uv run nextcloud-mcp-server --oauth
+
+# Or with custom options
+uv run nextcloud-mcp-server --oauth --port 8000 --log-level info
+```
+
+### Verify Startup
+
+Look for these success messages:
+
+**For Mode A (Auto-registration)**:
+```
+INFO     OAuth mode detected (NEXTCLOUD_USERNAME/PASSWORD not set)
+INFO     Configuring MCP server for OAuth mode
+INFO     Performing OIDC discovery: https://your.nextcloud.instance.com/.well-known/openid-configuration
+✓ PKCE support validated: ['S256']
+INFO     OIDC discovery successful
+INFO     Attempting dynamic client registration...
+INFO     Dynamic client registration successful
+INFO     OAuth client ready: <client-id>...
+INFO     Saved OAuth client credentials to .nextcloud_oauth_client.json
+INFO     OAuth initialization complete
+INFO     MCP server ready at http://127.0.0.1:8000
+```
+
+**For Mode B (Pre-configured)**:
+```
+INFO     OAuth mode detected (NEXTCLOUD_USERNAME/PASSWORD not set)
+INFO     Configuring MCP server for OAuth mode
+INFO     Performing OIDC discovery: https://your.nextcloud.instance.com/.well-known/openid-configuration
+✓ PKCE support validated: ['S256']
+INFO     OIDC discovery successful
+INFO     Using pre-configured OAuth client: abc123xyz789
+INFO     OAuth initialization complete
+INFO     MCP server ready at http://127.0.0.1:8000
+```
+
+### Common Startup Issues
+
+| Issue | Solution |
+|-------|----------|
+| "OAuth mode requires NEXTCLOUD_HOST" | Set `NEXTCLOUD_HOST` in `.env` |
+| "OIDC discovery failed" | Verify Nextcloud URL and network connectivity |
+| "Dynamic registration failed" | Enable dynamic registration in OIDC app settings |
+| "PKCE validation failed" | See [Upstream Status](oauth-upstream-status.md) |
+
+See [OAuth Troubleshooting](oauth-troubleshooting.md) for detailed solutions.
+
+## Testing Authentication
+
+### Test with MCP Inspector
+
+The MCP Inspector provides a web UI for testing:
+
+```bash
+# In a new terminal
+uv run mcp dev
+
+# Opens browser at http://localhost:6272
+```
+
+In the MCP Inspector UI:
+1. Enter server URL: `http://localhost:8000/mcp`
+2. Click **Connect**
+3. Complete OAuth flow in browser popup:
+   - Login to Nextcloud
+   - Authorize MCP server access
+   - Redirected back to MCP Inspector
+4. Test tools:
+   - Try `nc_notes_create_note`
+   - Try `nc_notes_search_notes`
+   - Try `nc_calendar_list_events`
+
+### Test from Command Line
+
+```bash
+# Get an OAuth token (you'll need to implement client flow or extract from browser)
+TOKEN="your_access_token_here"
+
+# Test OCS API (should work)
+curl -H "Authorization: Bearer $TOKEN" \
+  "$NEXTCLOUD_HOST/ocs/v2.php/cloud/capabilities?format=json" \
+  -H "OCS-APIRequest: true"
+
+# Test Notes API (requires upstream patch)
+curl -H "Authorization: Bearer $TOKEN" \
+  "$NEXTCLOUD_HOST/apps/notes/api/v1/notes"
+```
+
+### Verify Token Validation
+
+Check MCP server logs for token validation:
+
+```bash
+# Start server with debug logging
+uv run nextcloud-mcp-server --oauth --log-level debug
+
+# Look for:
+# DEBUG    Token validation via userinfo endpoint
+# DEBUG    Token validated successfully for user: username
+```
+
+## Production Recommendations
+
+### Security Best Practices
+
+1. **Use Pre-configured Clients** (Mode B)
+   - More stable
+   - Better audit trails
+   - No expiration issues
+
+2. **Secure Credential Storage**
+   ```bash
+   # Set restrictive permissions
+   chmod 600 .nextcloud_oauth_client.json
+   chmod 600 .env
+   ```
+
+3. **Use HTTPS for MCP Server**
+   - Especially important for remote access
+   - Use reverse proxy (nginx, Apache) with SSL
+
+4. **Restrict Redirect URIs**
+   - Only register necessary redirect URIs
+   - Use specific URLs (not wildcards)
+
+### Deployment Considerations
+
+1. **MCP Server URL**
+   - Must be accessible to OAuth clients
+   - Must match redirect URI registered with Nextcloud
+   - For Docker: expose port and use correct host
+
+2. **Network Configuration**
+   - MCP server must reach Nextcloud (OIDC endpoints)
+   - OAuth clients must reach MCP server (callbacks)
+   - OAuth clients must reach Nextcloud (authorization flow)
+
+3. **Process Management**
+   - Use systemd, supervisord, or Docker for MCP server
+   - Ensure automatic restart on failure
+   - Monitor logs for OAuth errors
+
+### Example Production Configs
+
+#### Docker Compose
+
+```yaml
+version: '3'
+services:
+  nextcloud-mcp:
+    image: ghcr.io/cbcoutinho/nextcloud-mcp-server:latest
+    ports:
+      - "127.0.0.1:8000:8000"
+    environment:
+      NEXTCLOUD_HOST: https://your.nextcloud.instance.com
+      NEXTCLOUD_OIDC_CLIENT_ID: ${NEXTCLOUD_OIDC_CLIENT_ID}
+      NEXTCLOUD_OIDC_CLIENT_SECRET: ${NEXTCLOUD_OIDC_CLIENT_SECRET}
+      NEXTCLOUD_MCP_SERVER_URL: http://your-server:8000
+    volumes:
+      - ./oauth_client.json:/app/.nextcloud_oauth_client.json
+    command: ["--oauth", "--transport", "streamable-http"]
+    restart: unless-stopped
+```
+
+#### Systemd Service
+
+```ini
+[Unit]
+Description=Nextcloud MCP Server (OAuth)
+After=network.target
+
+[Service]
+Type=simple
+User=mcp
+WorkingDirectory=/opt/nextcloud-mcp-server
+Environment="NEXTCLOUD_HOST=https://your.nextcloud.instance.com"
+Environment="NEXTCLOUD_OIDC_CLIENT_ID=abc123xyz789"
+Environment="NEXTCLOUD_OIDC_CLIENT_SECRET=secret456def012"
+Environment="NEXTCLOUD_MCP_SERVER_URL=http://your-server:8000"
+ExecStart=/opt/nextcloud-mcp-server/.venv/bin/nextcloud-mcp-server --oauth
+Restart=on-failure
+RestartSec=10
+
+[Install]
+WantedBy=multi-user.target
+```
+
+### Monitoring and Maintenance
+
+1. **Log Monitoring**
+   ```bash
+   # Watch for OAuth errors
+   tail -f /var/log/nextcloud-mcp/server.log | grep -i "oauth\|token"
+   ```
+
+2. **Token Expiration** (Mode A only)
+   - Monitor for "Stored client has expired" messages
+   - Consider increasing expiration or switching to Mode B
+
+3. **Upstream Patches**
+   - Subscribe to [Upstream Status](oauth-upstream-status.md)
+   - Plan to update when patches are merged
+
+## Troubleshooting
+
+For OAuth-specific issues, see [OAuth Troubleshooting](oauth-troubleshooting.md).
+
+Common issues:
+- [OIDC discovery failed](oauth-troubleshooting.md#oidc-discovery-failed)
+- [Bearer token auth fails](oauth-troubleshooting.md#bearer-token-authentication-fails)
+- [Client expired](oauth-troubleshooting.md#client-expired)
+- [PKCE errors](oauth-troubleshooting.md#pkce-not-advertised)
+
+## Next Steps
+
+- [OAuth Architecture](oauth-architecture.md) - Understand how OAuth works
+- [OAuth Troubleshooting](oauth-troubleshooting.md) - Solve common issues
+- [Upstream Status](oauth-upstream-status.md) - Track required patches
+- [Configuration](configuration.md) - All environment variables
+- [Running the Server](running.md) - Additional server options
+
+## See Also
+
+- [Authentication Overview](authentication.md) - OAuth vs BasicAuth comparison
+- [Quick Start Guide](quickstart-oauth.md) - 5-minute setup for development
+- [MCP Specification](https://spec.modelcontextprotocol.io/) - MCP protocol details
+- [RFC 6749](https://www.rfc-editor.org/rfc/rfc6749) - OAuth 2.0 Framework
+- [RFC 7636](https://www.rfc-editor.org/rfc/rfc7636) - PKCE Extension

docs/oauth-troubleshooting.md

@@ -0,0 +1,554 @@
+# OAuth Troubleshooting
+
+This guide covers OAuth-specific issues and solutions for the Nextcloud MCP server.
+
+For general troubleshooting, see [Troubleshooting Guide](troubleshooting.md).
+
+## Quick Diagnosis
+
+Start here to identify your issue:
+
+| Symptom | Likely Cause | Quick Fix Link |
+|---------|--------------|----------------|
+| "OAuth mode requires NEXTCLOUD_HOST" | Missing environment variable | [Missing NEXTCLOUD_HOST](#missing-nextcloud_host) |
+| "OAuth mode requires client credentials OR dynamic registration" | OIDC apps not configured | [Missing OIDC Apps](#missing-or-misconfigured-oidc-apps) |
+| "PKCE support validation failed" | OIDC app doesn't advertise PKCE | [PKCE Not Advertised](#pkce-not-advertised) |
+| "Stored client has expired" | Dynamic client expired | [Client Expired](#client-expired) |
+| HTTP 401 for Notes API | Bearer token patch missing | [Bearer Token Auth Fails](#bearer-token-authentication-fails) |
+| "OIDC discovery failed" | Network or configuration issue | [Discovery Failed](#oidc-discovery-failed) |
+| "Permission denied" on .nextcloud_oauth_client.json | File permissions issue | [File Permission Error](#file-permission-error) |
+
+## Configuration Issues
+
+### Missing NEXTCLOUD_HOST
+
+**Error Message**:
+```
+OAuth mode requires NEXTCLOUD_HOST environment variable
+```
+
+**Cause**: The `NEXTCLOUD_HOST` environment variable is not set or empty.
+
+**Solution**:
+
+1. Add to your `.env` file:
+   ```bash
+   NEXTCLOUD_HOST=https://your.nextcloud.instance.com
+   ```
+
+2. Reload environment variables:
+   ```bash
+   export $(grep -v '^#' .env | xargs)
+   ```
+
+3. Verify it's set:
+   ```bash
+   echo $NEXTCLOUD_HOST
+   # Should output: https://your.nextcloud.instance.com
+   ```
+
+---
+
+### Missing or Misconfigured OIDC Apps
+
+**Error Message**:
+```
+OAuth mode requires either client credentials OR dynamic client registration
+```
+
+**Cause**: The required Nextcloud OIDC apps are either:
+- Not installed
+- Not enabled
+- Missing configuration
+
+**Solution**:
+
+**Step 1**: Verify both apps are installed:
+
+```bash
+# Check installed apps
+php occ app:list | grep -E "oidc|user_oidc"
+
+# Should show:
+#  - oidc: enabled
+#  - user_oidc: enabled
+```
+
+If not installed:
+1. Open Nextcloud as administrator
+2. Navigate to **Apps** → **Security**
+3. Install **"OIDC"** (OIDC Identity Provider)
+4. Install **"OpenID Connect user backend"** (user_oidc)
+5. Enable both apps
+
+**Step 2**: Enable dynamic client registration:
+
+1. Go to **Settings** → **OIDC** (Administration)
+2. Enable **"Allow dynamic client registration"**
+
+**Step 3**: Configure Bearer token validation:
+
+```bash
+php occ config:system:set user_oidc oidc_provider_bearer_validation --value=true --type=boolean
+```
+
+**Step 4**: Verify discovery endpoint:
+
+```bash
+curl https://your.nextcloud.instance.com/.well-known/openid-configuration | jq '.registration_endpoint'
+
+# Should output:
+# "https://your.nextcloud.instance.com/apps/oidc/register"
+```
+
+**Alternative**: Use pre-configured client credentials:
+
+```bash
+# Register client via CLI
+php occ oidc:create \
+  --name="Nextcloud MCP Server" \
+  --type=confidential \
+  --redirect-uri="http://localhost:8000/oauth/callback"
+
+# Add to .env
+echo "NEXTCLOUD_OIDC_CLIENT_ID=<client-id>" >> .env
+echo "NEXTCLOUD_OIDC_CLIENT_SECRET=<client-secret>" >> .env
+```
+
+---
+
+### Client Expired
+
+**Error Message**:
+```
+Stored client has expired
+```
+
+**Cause**: Dynamically registered OAuth clients expire (default: 1 hour).
+
+**Solution**:
+
+**Option 1: Restart the Server** (Automatic re-registration)
+
+```bash
+uv run nextcloud-mcp-server --oauth
+# Server automatically re-registers if credentials expired
+```
+
+**Option 2: Use Pre-configured Credentials** (Recommended for production)
+
+```bash
+# Register permanent client via Nextcloud CLI
+php occ oidc:create \
+  --name="Nextcloud MCP Server" \
+  --type=confidential \
+  --redirect-uri="http://localhost:8000/oauth/callback"
+
+# Add to .env
+NEXTCLOUD_OIDC_CLIENT_ID=<from-output>
+NEXTCLOUD_OIDC_CLIENT_SECRET=<from-output>
+```
+
+Pre-configured clients don't expire.
+
+**Option 3: Increase Expiration Time**
+
+```bash
+# Via Nextcloud CLI (default: 3600 seconds = 1 hour)
+php occ config:app:set oidc expire_time --value "86400"  # 24 hours
+```
+
+---
+
+### File Permission Error
+
+**Error Message**:
+```
+Permission denied when reading/writing .nextcloud_oauth_client.json
+```
+
+**Cause**: The server cannot access the OAuth client storage file.
+
+**Solution**:
+
+```bash
+# Check file permissions
+ls -la .nextcloud_oauth_client.json
+
+# Fix file permissions (owner read/write only)
+chmod 600 .nextcloud_oauth_client.json
+
+# Ensure directory is writable
+chmod 755 $(dirname .nextcloud_oauth_client.json)
+
+# If file doesn't exist, ensure directory is writable
+mkdir -p $(dirname .nextcloud_oauth_client.json)
+```
+
+For custom storage paths:
+```bash
+# Set custom path in .env
+NEXTCLOUD_OIDC_CLIENT_STORAGE=/path/to/custom/oauth_client.json
+
+# Ensure directory exists and is writable
+mkdir -p $(dirname /path/to/custom/oauth_client.json)
+chmod 755 $(dirname /path/to/custom/oauth_client.json)
+```
+
+---
+
+## Discovery and Connection Issues
+
+### OIDC Discovery Failed
+
+**Error Message**:
+```
+OIDC discovery failed
+Cannot reach OIDC discovery endpoint
+```
+
+**Cause**: The server cannot reach the Nextcloud OIDC discovery endpoint.
+
+**Solution**:
+
+**Step 1**: Verify Nextcloud URL is correct:
+
+```bash
+echo $NEXTCLOUD_HOST
+# Should be full URL: https://your.nextcloud.instance.com
+```
+
+**Step 2**: Test discovery endpoint manually:
+
+```bash
+curl https://your.nextcloud.instance.com/.well-known/openid-configuration
+
+# Should return JSON with OIDC configuration
+# {
+#   "issuer": "https://your.nextcloud.instance.com",
+#   "authorization_endpoint": "https://your.nextcloud.instance.com/apps/oidc/authorize",
+#   ...
+# }
+```
+
+**Step 3**: Check network connectivity:
+
+```bash
+# Test basic connectivity
+ping your.nextcloud.instance.com
+
+# Test HTTPS
+curl -I https://your.nextcloud.instance.com
+```
+
+**Step 4**: Verify both OIDC apps are enabled:
+
+```bash
+php occ app:list | grep -E "oidc|user_oidc"
+```
+
+**Step 5**: Check firewall rules (if using Docker):
+
+```bash
+# Check if MCP server can reach Nextcloud
+docker exec nextcloud-mcp-server curl https://your.nextcloud.instance.com/.well-known/openid-configuration
+```
+
+---
+
+## Authentication Issues
+
+### Bearer Token Authentication Fails
+
+**Error Message**:
+```
+HTTP 401 Unauthorized when calling Nextcloud APIs
+```
+
+**Symptoms**:
+- OCS APIs work (`/ocs/v2.php/cloud/capabilities`)
+- App APIs fail (`/apps/notes/api/`, `/apps/calendar/`, etc.)
+
+**Cause**: The `user_oidc` app's CORS middleware interferes with Bearer token authentication for non-OCS endpoints.
+
+**Solution**: Apply the Bearer token patch to `user_oidc` app.
+
+See [Upstream Status](oauth-upstream-status.md#1-bearer-token-support-for-non-ocs-endpoints) for details.
+
+**Quick Patch**:
+
+```bash
+# SSH into Nextcloud server
+cd /path/to/nextcloud/apps/user_oidc
+
+# Edit lib/User/Backend.php
+# Add this line before each return statement in getCurrentUserId() method:
+$this->session->set('app_api', true);
+
+# Lines to modify: ~243, ~310, ~315, ~337
+```
+
+**Test the fix**:
+
+```bash
+# Get an OAuth token (from MCP client or test)
+TOKEN="your_access_token"
+
+# Test Notes API
+curl -H "Authorization: Bearer $TOKEN" \
+  https://your.nextcloud.instance.com/apps/notes/api/v1/notes
+
+# Should return notes JSON (not 401)
+```
+
+---
+
+### PKCE Not Advertised
+
+**Error Message**:
+```
+ERROR: OIDC CONFIGURATION ERROR - Missing PKCE Support Advertisement
+⚠️  MCP clients (like Claude Code) WILL REJECT this provider!
+```
+
+**Cause**: The OIDC discovery endpoint doesn't include `code_challenge_methods_supported` field.
+
+**Impact**:
+- Some MCP clients may refuse to connect
+- Standards compliance issue (RFC 8414)
+- **Functionality still works** (PKCE is accepted, just not advertised)
+
+**Solution**:
+
+**Short-term**: The MCP server logs a warning but continues. OAuth flow still works.
+
+**Long-term**: Update the `oidc` app to advertise PKCE support.
+
+See [Upstream Status](oauth-upstream-status.md#2-pkce-support-advertisement-in-discovery) for tracking.
+
+**Verify**:
+
+```bash
+curl https://your.nextcloud.instance.com/.well-known/openid-configuration | jq '.code_challenge_methods_supported'
+
+# Should return:
+# ["S256", "plain"]
+
+# If null, PKCE isn't advertised (but still works)
+```
+
+---
+
+## Runtime Issues
+
+### MCP Client Can't Authenticate
+
+**Symptoms**:
+- Client connects but OAuth flow fails
+- Authorization redirects don't work
+- Token exchange fails
+
+**Diagnosis**:
+
+**Step 1**: Verify OAuth is configured correctly:
+
+```bash
+uv run nextcloud-mcp-server --oauth --log-level debug
+```
+
+Look for:
+```
+INFO     OAuth initialization complete
+INFO     MCP server ready at http://127.0.0.1:8000
+```
+
+**Step 2**: Check OIDC discovery:
+
+```bash
+curl https://your.nextcloud.instance.com/.well-known/openid-configuration
+```
+
+**Step 3**: Verify MCP server URL matches client expectations:
+
+```bash
+echo $NEXTCLOUD_MCP_SERVER_URL
+# Should match the URL clients use to connect
+# Default: http://localhost:8000
+```
+
+If MCP server is on a different host/port, update:
+```bash
+NEXTCLOUD_MCP_SERVER_URL=http://actual-host:actual-port
+```
+
+**Step 4**: Check redirect URI configuration:
+
+For pre-configured clients, ensure redirect URI matches:
+```bash
+# Client redirect URI should be:
+http://your-mcp-server-url/oauth/callback
+
+# Example for local server:
+http://localhost:8000/oauth/callback
+```
+
+---
+
+### Tools Return 401 Errors
+
+**Symptoms**:
+- OAuth flow completes successfully
+- Token is valid
+- MCP tools return 401 errors
+
+**Cause**: Bearer token not working with Nextcloud APIs.
+
+**Solution**: See [Bearer Token Authentication Fails](#bearer-token-authentication-fails) above.
+
+---
+
+## Switching Authentication Modes
+
+### From BasicAuth to OAuth
+
+```bash
+# 1. Remove or comment out USERNAME/PASSWORD in .env
+sed -i 's/^NEXTCLOUD_USERNAME/#NEXTCLOUD_USERNAME/' .env
+sed -i 's/^NEXTCLOUD_PASSWORD/#NEXTCLOUD_PASSWORD/' .env
+
+# 2. Ensure NEXTCLOUD_HOST is set
+grep NEXTCLOUD_HOST .env
+
+# 3. Restart server with OAuth
+export $(grep -v '^#' .env | xargs)
+uv run nextcloud-mcp-server --oauth
+```
+
+### From OAuth to BasicAuth
+
+```bash
+# 1. Add USERNAME/PASSWORD to .env
+echo "NEXTCLOUD_USERNAME=your-username" >> .env
+echo "NEXTCLOUD_PASSWORD=your-password" >> .env
+
+# 2. Restart server (BasicAuth auto-detected)
+export $(grep -v '^#' .env | xargs)
+uv run nextcloud-mcp-server --no-oauth
+```
+
+---
+
+## Advanced Debugging
+
+### Enable Debug Logging
+
+```bash
+uv run nextcloud-mcp-server --oauth --log-level debug
+```
+
+Look for:
+- OIDC discovery details
+- Client registration attempts
+- Token validation logs
+- API request/response details
+
+### Test Discovery Endpoint
+
+```bash
+# Full discovery response
+curl https://your.nextcloud.instance.com/.well-known/openid-configuration | jq
+
+# Check specific fields
+curl https://your.nextcloud.instance.com/.well-known/openid-configuration | jq '{
+  issuer,
+  authorization_endpoint,
+  token_endpoint,
+  userinfo_endpoint,
+  registration_endpoint,
+  code_challenge_methods_supported
+}'
+```
+
+### Test Token Validation
+
+```bash
+# Get userinfo with token
+curl -H "Authorization: Bearer $TOKEN" \
+  https://your.nextcloud.instance.com/apps/oidc/userinfo
+
+# Should return user info:
+# {
+#   "sub": "username",
+#   "preferred_username": "username",
+#   "name": "Display Name",
+#   ...
+# }
+```
+
+### Test Nextcloud API Access
+
+```bash
+# Test OCS API (should work)
+curl -H "Authorization: Bearer $TOKEN" \
+  "$NEXTCLOUD_HOST/ocs/v2.php/cloud/capabilities?format=json" \
+  -H "OCS-APIRequest: true"
+
+# Test app API (requires patch)
+curl -H "Authorization: Bearer $TOKEN" \
+  "$NEXTCLOUD_HOST/apps/notes/api/v1/notes"
+```
+
+---
+
+## Getting Help
+
+If you continue to experience issues:
+
+### 1. Collect Diagnostic Information
+
+```bash
+# Server version
+uv run nextcloud-mcp-server --version
+
+# Python version
+python3 --version
+
+# Server logs with debug
+uv run nextcloud-mcp-server --oauth --log-level debug 2>&1 | tee mcp-server.log
+
+# OIDC discovery
+curl https://your.nextcloud.instance.com/.well-known/openid-configuration > oidc-discovery.json
+
+# Nextcloud version
+# Check in Nextcloud admin panel or:
+php occ -V
+```
+
+### 2. Check Documentation
+
+- [OAuth Architecture](oauth-architecture.md) - How OAuth works
+- [OAuth Setup Guide](oauth-setup.md) - Configuration steps
+- [Upstream Status](oauth-upstream-status.md) - Required patches
+- [Configuration](configuration.md) - Environment variables
+
+### 3. Open an Issue
+
+If problems persist, [open an issue](https://github.com/cbcoutinho/nextcloud-mcp-server/issues) with:
+
+- **Error messages** (full text)
+- **Server logs** (with `--log-level debug`)
+- **OIDC discovery response** (from curl command above)
+- **Nextcloud version**
+- **OIDC app versions** (`oidc` and `user_oidc`)
+- **Steps to reproduce**
+- **Environment details** (OS, Python version, Docker vs local)
+
+---
+
+## See Also
+
+- [OAuth Quick Start](quickstart-oauth.md) - Get started quickly
+- [OAuth Setup Guide](oauth-setup.md) - Detailed configuration
+- [OAuth Architecture](oauth-architecture.md) - Technical details
+- [Upstream Status](oauth-upstream-status.md) - Required patches
+- [General Troubleshooting](troubleshooting.md) - Non-OAuth issues

docs/oauth-upstream-status.md

@@ -0,0 +1,226 @@
+# OAuth Upstream Status
+
+This document tracks the status of upstream patches and pull requests required for full OAuth functionality.
+
+## Overview
+
+The Nextcloud MCP Server's OAuth implementation relies on two Nextcloud apps:
+- **`oidc`** - OIDC Identity Provider (Authorization Server)
+- **`user_oidc`** - OpenID Connect user backend (Token validation)
+
+While the core OAuth flow works, there are **pending upstream improvements** that enhance functionality and standards compliance.
+
+## Required Patches
+
+### 1. Bearer Token Support for Non-OCS Endpoints
+
+**Status**: 🟡 **Patch Required** (Pending Upstream)
+
+**Affected Component**: `user_oidc` app
+
+**Issue**: Bearer token authentication fails for app-specific APIs (Notes, Calendar, etc.) with `401 Unauthorized` errors, even though OCS APIs work correctly.
+
+**Root Cause**: The `CORSMiddleware` in Nextcloud logs out sessions created by Bearer token authentication when CSRF tokens are missing, which breaks API requests.
+
+**Solution**: Set the `app_api` session flag during Bearer token authentication to bypass CSRF checks.
+
+**Upstream PR**: [nextcloud/user_oidc#1221](https://github.com/nextcloud/user_oidc/issues/1221)
+
+**Workaround**: Manually apply the patch to `lib/User/Backend.php` in the `user_oidc` app
+
+**Impact**:
+- ✅ **Works**: OCS APIs (`/ocs/v2.php/cloud/capabilities`)
+- ❌ **Requires Patch**: App APIs (`/apps/notes/api/`, `/apps/calendar/`, etc.)
+
+**Files Modified**: `lib/User/Backend.php` in `user_oidc` app
+
+**Patch Summary**:
+```php
+// Add before successful Bearer token authentication returns
+$this->session->set('app_api', true);
+```
+
+This is added at lines ~243, ~310, ~315, and ~337 in `Backend.php`.
+
+---
+
+### 2. PKCE Support Advertisement in Discovery
+
+**Status**: 🟢 **PR Submitted** (Pending Review)
+
+**Affected Component**: `oidc` app
+
+**Issue**: The OIDC discovery endpoint (`/.well-known/openid-configuration`) does not advertise PKCE support in the `code_challenge_methods_supported` field.
+
+**Why It Matters**:
+- MCP specification requires PKCE with S256 code challenge method
+- RFC 8414 states that absence of `code_challenge_methods_supported` means PKCE is **not supported**
+- Some MCP clients may reject providers without proper PKCE advertisement
+
+**Current Behavior**:
+- PKCE **functionally works** (the OIDC app accepts and validates PKCE)
+- PKCE just isn't **advertised** in discovery metadata
+
+**Recommended Fix**: Update `oidc` app to include:
+```json
+{
+  "code_challenge_methods_supported": ["S256"]
+}
+```
+
+**Workaround**: The MCP server implements PKCE validation and logs a warning if not advertised. Functionality still works.
+
+**Upstream PR**: [H2CK/oidc#584](https://github.com/H2CK/oidc/pull/584) - Submitted 2025-10-13
+- **Changes**: Adds `code_challenge_methods_supported: ["S256"]` to discovery document when PKCE is enabled
+- **Size**: +5 lines added, 0 deleted
+- **Status**: Open, awaiting review
+
+---
+
+## Upstream PRs Status
+
+| PR/Issue | Component | Status | Priority | Notes |
+|----------|-----------|--------|----------|-------|
+| [user_oidc#1221](https://github.com/nextcloud/user_oidc/issues/1221) | `user_oidc` | 🟡 Open | High | Required for app-specific APIs |
+| [H2CK/oidc#584](https://github.com/H2CK/oidc/pull/584) | `oidc` | 🟢 PR Open | Medium | PKCE advertisement for standards compliance |
+
+## What Works Without Patches
+
+The following functionality works **out of the box** without any patches:
+
+✅ **OAuth Flow**:
+- OIDC discovery
+- Dynamic client registration
+- Authorization code flow with PKCE
+- Token exchange
+- Userinfo endpoint
+
+✅ **MCP Server as Resource Server**:
+- Token validation via userinfo
+- Per-user client instances
+- Token caching
+
+✅ **Nextcloud OCS APIs**:
+- Capabilities endpoint
+- All OCS-based APIs
+
+## What Requires Patches
+
+The following functionality requires upstream patches:
+
+🟡 **App-Specific APIs** (Requires user_oidc#1221):
+- Notes API (`/apps/notes/api/`)
+- Calendar API (CalDAV)
+- Contacts API (CardDAV)
+- Deck API
+- Tables API
+- Custom app APIs
+
+🟡 **Standards Compliance** (PKCE advertisement):
+- Full RFC 8414 compliance
+- MCP client compatibility guarantee
+
+## Installation Instructions
+
+### For Development/Testing
+
+If the upstream PRs are not yet merged, you can apply patches manually:
+
+#### 1. Apply Bearer Token Patch
+
+```bash
+# SSH into Nextcloud server
+cd /path/to/nextcloud/apps/user_oidc
+
+# Download and apply patch
+# (Patch file to be created once PR is ready)
+wget https://github.com/nextcloud/user_oidc/pull/XXXX.patch
+git apply XXXX.patch
+
+# Or manually edit lib/User/Backend.php
+# Add this line before each return statement in getCurrentUserId():
+#   $this->session->set('app_api', true);
+```
+
+#### 2. Verify Installation
+
+```bash
+# Test with OAuth token
+curl -H "Authorization: Bearer YOUR_TOKEN" \
+  https://your.nextcloud.com/apps/notes/api/v1/notes
+
+# Should return notes JSON (not 401)
+```
+
+### For Production
+
+**Recommendation**: Wait for upstream PRs to be merged and included in official Nextcloud releases before deploying OAuth in production.
+
+**Alternative**: Use a patched version of `user_oidc` app in your deployment:
+1. Fork the `user_oidc` app
+2. Apply the required patches
+3. Install your patched version
+4. Document the changes for your team
+
+## Testing
+
+The integration test suite validates OAuth functionality:
+
+```bash
+# Start OAuth-enabled MCP server
+docker-compose up --build -d mcp-oauth
+
+# Run comprehensive OAuth tests
+uv run pytest tests/integration/test_oauth_playwright.py --browser firefox -v
+
+# Tests verify:
+# - OAuth flow completion
+# - Token validation
+# - MCP tool calls with Bearer tokens
+# - Notes API access (requires patch)
+```
+
+## Monitoring Upstream Progress
+
+To track progress on these issues:
+
+1. **Watch the upstream repositories**:
+   - [nextcloud/user_oidc](https://github.com/nextcloud/user_oidc)
+   - [nextcloud/oidc](https://github.com/nextcloud/oidc)
+
+2. **Subscribe to specific issues**:
+   - [user_oidc#1221](https://github.com/nextcloud/user_oidc/issues/1221) - Bearer token support
+
+3. **Check Nextcloud release notes** for mentions of:
+   - Bearer token authentication improvements
+   - OIDC/OAuth enhancements
+   - AppAPI compatibility
+
+## Contributing
+
+Want to help get these patches merged?
+
+1. **Test the patches**: Run the integration tests and report results
+2. **Review PRs**: Provide feedback on upstream pull requests
+3. **Document issues**: Report any problems or edge cases
+4. **Contribute code**: Submit improvements or fixes to upstream
+
+## Timeline Expectations
+
+**Best Case**: PRs merged in next Nextcloud minor release (est. 3-6 months)
+
+**Realistic**: PRs reviewed and merged within 6-12 months
+
+**Meanwhile**: Use the workarounds documented in this guide
+
+## See Also
+
+- [OAuth Architecture](oauth-architecture.md) - How OAuth works in this implementation
+- [OAuth Troubleshooting](oauth-troubleshooting.md) - Common issues and solutions
+- [OAuth Setup Guide](oauth-setup.md) - Configuration instructions
+
+---
+
+**Last Updated**: 2025-10-14
+
+**Next Review**: When PR #584 or issue #1221 has activity

docs/quickstart-oauth.md

@@ -0,0 +1,163 @@
+# OAuth Quick Start Guide
+
+Get up and running with OAuth authentication in 5 minutes.
+
+## Prerequisites Checklist
+
+Before you begin, ensure you have:
+
+- [ ] Nextcloud instance with **administrator access**
+- [ ] Nextcloud version 28 or later
+- [ ] Python 3.11+ installed
+- [ ] `uv` package manager installed ([installation instructions](https://docs.astral.sh/uv/getting-started/installation/))
+
+## Step 1: Install Nextcloud Apps
+
+Install **both** required apps in your Nextcloud instance:
+
+1. Open Nextcloud as administrator
+2. Navigate to **Apps** → **Security**
+3. Install:
+   - **OIDC** (OIDC Identity Provider app)
+   - **OpenID Connect user backend** (user_oidc app)
+4. Enable both apps
+
+> [!IMPORTANT]
+> The `user_oidc` app requires an upstream patch for Bearer token support. See [Upstream Status](oauth-upstream-status.md) for details. The functionality works, but the PR is pending.
+
+## Step 2: Configure Nextcloud OIDC
+
+Enable dynamic client registration and Bearer token validation:
+
+### Via Web UI
+
+1. Go to **Settings** → **OIDC** (Administration settings)
+2. Enable **"Allow dynamic client registration"**
+
+### Via CLI (Required)
+
+SSH into your Nextcloud server and run:
+
+```bash
+# Enable Bearer token validation
+php occ config:system:set user_oidc oidc_provider_bearer_validation --value=true --type=boolean
+```
+
+## Step 3: Install MCP Server
+
+Clone and install the MCP server:
+
+```bash
+# Clone repository
+git clone https://github.com/cbcoutinho/nextcloud-mcp-server.git
+cd nextcloud-mcp-server
+
+# Install dependencies
+uv sync
+```
+
+## Step 4: Configure Environment
+
+Create a `.env` file with minimal configuration:
+
+```bash
+# Copy sample
+cp env.sample .env
+
+# Edit .env and set:
+NEXTCLOUD_HOST=https://your.nextcloud.instance.com
+
+# IMPORTANT: Leave these EMPTY for OAuth mode
+NEXTCLOUD_USERNAME=
+NEXTCLOUD_PASSWORD=
+```
+
+## Step 5: Start the Server
+
+Load environment variables and start the server:
+
+```bash
+# Load environment
+export $(grep -v '^#' .env | xargs)
+
+# Start server with OAuth
+uv run nextcloud-mcp-server --oauth
+```
+
+Look for this success message:
+
+```
+✓ PKCE support validated: ['S256']
+INFO     OAuth initialization complete
+INFO     MCP server ready at http://127.0.0.1:8000
+```
+
+## Step 6: Test with MCP Inspector
+
+Open a new terminal and test the connection:
+
+```bash
+# Start MCP Inspector
+uv run mcp dev
+```
+
+This opens your browser. In the MCP Inspector UI:
+
+1. Enter server URL: `http://127.0.0.1:8000/mcp`
+2. Click **Connect**
+3. Complete the OAuth flow in the browser popup
+4. After authorization, you'll see available tools and resources
+
+Test a tool by trying:
+- **Tool**: `nc_notes_create_note`
+- **Title**: "Test Note"
+- **Content**: "Hello from MCP!"
+- **Category**: "Notes"
+
+## Troubleshooting Quick Fixes
+
+### PKCE Error
+
+If you see:
+```
+ERROR: OIDC CONFIGURATION ERROR - Missing PKCE Support Advertisement
+```
+
+**Fix**: The Nextcloud OIDC app needs to be updated to advertise PKCE support. See [Upstream Status](oauth-upstream-status.md) for the required PR.
+
+### 401 Unauthorized for Notes API
+
+If OAuth works but Notes API returns 401:
+
+**Fix**: The `user_oidc` app needs the Bearer token patch. See [Upstream Status](oauth-upstream-status.md) for details.
+
+### Can't Reach OIDC Discovery Endpoint
+
+**Fix**: Verify your Nextcloud URL is correct and accessible:
+
+```bash
+curl https://your.nextcloud.instance.com/.well-known/openid-configuration
+```
+
+## Next Steps
+
+- [OAuth Setup Guide](oauth-setup.md) - Detailed configuration options
+- [OAuth Architecture](oauth-architecture.md) - How it works under the hood
+- [OAuth Troubleshooting](oauth-troubleshooting.md) - Common issues and solutions
+- [Configuration](configuration.md) - All environment variables
+
+## Development vs Production
+
+This quick start uses **automatic client registration** which is perfect for:
+- Development
+- Testing
+- Short-lived deployments
+
+For **production deployments**, you should:
+1. Pre-register OAuth clients manually
+2. Use dedicated client credentials
+3. See [OAuth Setup Guide](oauth-setup.md) for production configuration
+
+---
+
+**Need help?** Check [OAuth Troubleshooting](oauth-troubleshooting.md) or [open an issue](https://github.com/cbcoutinho/nextcloud-mcp-server/issues).

docs/running.md

@@ -0,0 +1,440 @@
+# Running the Server
+
+This guide covers different ways to start and run the Nextcloud MCP server.
+
+## Prerequisites
+
+Before running the server:
+
+1. **Install the server** - See [Installation Guide](installation.md)
+2. **Configure environment** - See [Configuration Guide](configuration.md)
+3. **Set up authentication** - See [OAuth Setup](oauth-setup.md) or [Authentication](authentication.md)
+
+---
+
+## Quick Start
+
+Load your environment variables and start the server:
+
+```bash
+# Load environment variables from .env
+export $(grep -v '^#' .env | xargs)
+
+# Start the server
+uv run nextcloud-mcp-server
+```
+
+The server will start on `http://127.0.0.1:8000` by default.
+
+---
+
+## Running Locally
+
+### Method 1: Using nextcloud-mcp-server CLI (Recommended)
+
+The CLI provides a simple interface with built-in defaults:
+
+#### OAuth Mode
+
+```bash
+# Auto-detected when NEXTCLOUD_USERNAME/PASSWORD not set
+uv run nextcloud-mcp-server
+
+# Explicitly force OAuth mode
+uv run nextcloud-mcp-server --oauth
+
+# OAuth with custom host and port
+uv run nextcloud-mcp-server --oauth --host 0.0.0.0 --port 8080
+
+# OAuth with pre-configured client
+uv run nextcloud-mcp-server --oauth \
+  --oauth-client-id abc123 \
+  --oauth-client-secret xyz789
+
+# OAuth with specific apps only
+uv run nextcloud-mcp-server --oauth \
+  --enable-app notes \
+  --enable-app calendar
+```
+
+#### BasicAuth Mode (Legacy)
+
+```bash
+# Auto-detected when NEXTCLOUD_USERNAME/PASSWORD are set
+uv run nextcloud-mcp-server
+
+# Explicitly force BasicAuth mode
+uv run nextcloud-mcp-server --no-oauth
+
+# BasicAuth with specific apps
+uv run nextcloud-mcp-server --no-oauth \
+  --enable-app notes \
+  --enable-app webdav
+```
+
+### Method 2: Using uvicorn
+
+For more control over server options (workers, reload, etc.):
+
+```bash
+# Load environment variables
+export $(grep -v '^#' .env | xargs)
+
+# Run with uvicorn
+uv run uvicorn nextcloud_mcp_server.app:get_app \
+  --factory \
+  --host 127.0.0.1 \
+  --port 8000 \
+  --reload  # Enable auto-reload for development
+```
+
+See all uvicorn options at [https://www.uvicorn.org/settings/](https://www.uvicorn.org/settings/)
+
+### Method 3: Using Python Module
+
+```bash
+# Load environment variables
+export $(grep -v '^#' .env | xargs)
+
+# Run as Python module
+python -m nextcloud_mcp_server.app --oauth --port 8000
+```
+
+---
+
+## Running with Docker
+
+### Basic Docker Run
+
+```bash
+# OAuth mode
+docker run -p 127.0.0.1:8000:8000 --env-file .env --rm \
+  ghcr.io/cbcoutinho/nextcloud-mcp-server:latest --oauth
+
+# BasicAuth mode
+docker run -p 127.0.0.1:8000:8000 --env-file .env --rm \
+  ghcr.io/cbcoutinho/nextcloud-mcp-server:latest
+```
+
+### Docker with Persistent OAuth Storage
+
+```bash
+docker run -p 127.0.0.1:8000:8000 --env-file .env \
+  -v $(pwd)/.oauth:/app/.oauth \
+  --rm ghcr.io/cbcoutinho/nextcloud-mcp-server:latest --oauth
+```
+
+### Docker Compose
+
+Create `docker-compose.yml`:
+
+```yaml
+version: '3.8'
+
+services:
+  mcp:
+    image: ghcr.io/cbcoutinho/nextcloud-mcp-server:latest
+    command: --oauth --enable-app notes --enable-app calendar
+    ports:
+      - "127.0.0.1:8000:8000"
+    env_file:
+      - .env
+    volumes:
+      - ./oauth-storage:/app/.oauth
+    restart: unless-stopped
+```
+
+Start the service:
+
+```bash
+# Start in foreground
+docker-compose up
+
+# Start in background
+docker-compose up -d
+
+# View logs
+docker-compose logs -f
+
+# Stop the service
+docker-compose down
+```
+
+---
+
+## Server Options
+
+### Host and Port
+
+```bash
+# Bind to all interfaces (accessible from network)
+uv run nextcloud-mcp-server --host 0.0.0.0 --port 8000
+
+# Bind to localhost only (default, more secure)
+uv run nextcloud-mcp-server --host 127.0.0.1 --port 8000
+
+# Use a different port
+uv run nextcloud-mcp-server --port 8080
+```
+
+**Security Note:** Using `--host 0.0.0.0` exposes the server to your network. Only use this if you understand the security implications.
+
+### Transport Protocols
+
+The server supports multiple MCP transport protocols:
+
+```bash
+# Streamable HTTP (recommended)
+uv run nextcloud-mcp-server --transport streamable-http
+
+# SSE - Server-Sent Events (default, deprecated)
+uv run nextcloud-mcp-server --transport sse
+
+# HTTP
+uv run nextcloud-mcp-server --transport http
+```
+
+> [!WARNING]
+> SSE transport is deprecated and will be removed in a future version of the MCP spec. Please migrate to `streamable-http`.
+
+### Logging
+
+```bash
+# Set log level (critical, error, warning, info, debug, trace)
+uv run nextcloud-mcp-server --log-level debug
+
+# Production: use warning or error
+uv run nextcloud-mcp-server --log-level warning
+```
+
+### Selective App Enablement
+
+By default, all supported Nextcloud apps are enabled. You can enable specific apps only:
+
+```bash
+# Available apps: notes, tables, webdav, calendar, contacts, deck
+
+# Enable all apps (default)
+uv run nextcloud-mcp-server
+
+# Enable only Notes
+uv run nextcloud-mcp-server --enable-app notes
+
+# Enable multiple apps
+uv run nextcloud-mcp-server \
+  --enable-app notes \
+  --enable-app calendar \
+  --enable-app contacts
+
+# Enable only WebDAV for file operations
+uv run nextcloud-mcp-server --enable-app webdav
+```
+
+**Use cases:**
+- Reduce memory usage and startup time
+- Limit functionality for security/organizational reasons
+- Test specific app integrations
+- Run lightweight instances with only needed features
+
+---
+
+## Development Mode
+
+For active development with auto-reload:
+
+```bash
+# Using uvicorn with reload
+uv run uvicorn nextcloud_mcp_server.app:get_app \
+  --factory \
+  --reload \
+  --host 127.0.0.1 \
+  --port 8000 \
+  --log-level debug
+```
+
+Or use the CLI with reload flag:
+
+```bash
+uv run nextcloud-mcp-server --reload --log-level debug
+```
+
+---
+
+## Connecting to the Server
+
+### Using MCP Inspector
+
+MCP Inspector is a browser-based tool for testing MCP servers:
+
+```bash
+# Start MCP Inspector
+uv run mcp dev
+
+# In the browser:
+# 1. Enter server URL: http://localhost:8000
+# 2. Complete OAuth flow (if using OAuth)
+# 3. Explore tools and resources
+```
+
+### Using MCP Clients
+
+MCP clients (like Claude Desktop, LLM IDEs) can connect to your server:
+
+1. Configure the client with your server URL
+2. Complete OAuth authentication (if enabled)
+3. Start interacting with Nextcloud through the LLM
+
+---
+
+## Verifying Server Status
+
+### Check Server Health
+
+```bash
+# Test if server is responding
+curl http://localhost:8000/health
+
+# Expected response: HTTP 200 OK
+```
+
+### Check OAuth Configuration
+
+Look for these log messages on startup:
+
+**OAuth mode:**
+```
+INFO     OAuth mode detected (NEXTCLOUD_USERNAME/PASSWORD not set)
+INFO     Configuring MCP server for OAuth mode
+INFO     OIDC discovery successful
+INFO     OAuth client ready: <client-id>...
+INFO     OAuth initialization complete
+```
+
+**BasicAuth mode:**
+```
+INFO     BasicAuth mode detected (NEXTCLOUD_USERNAME/PASSWORD set)
+INFO     Initializing Nextcloud client with BasicAuth
+```
+
+---
+
+## Process Management
+
+### Running as a Background Service
+
+#### Using systemd (Linux)
+
+Create `/etc/systemd/system/nextcloud-mcp.service`:
+
+```ini
+[Unit]
+Description=Nextcloud MCP Server
+After=network.target
+
+[Service]
+Type=simple
+User=your-user
+WorkingDirectory=/path/to/nextcloud-mcp-server
+EnvironmentFile=/path/to/.env
+ExecStart=/path/to/uv run nextcloud-mcp-server --oauth
+Restart=on-failure
+RestartSec=10
+
+[Install]
+WantedBy=multi-user.target
+```
+
+Enable and start:
+
+```bash
+sudo systemctl daemon-reload
+sudo systemctl enable nextcloud-mcp
+sudo systemctl start nextcloud-mcp
+sudo systemctl status nextcloud-mcp
+```
+
+#### Using Docker Compose
+
+See [Docker Compose section](#docker-compose) above - includes `restart: unless-stopped`.
+
+### Monitoring Logs
+
+```bash
+# Local installation with systemd
+sudo journalctl -u nextcloud-mcp -f
+
+# Docker
+docker logs -f <container-name>
+
+# Docker Compose
+docker-compose logs -f mcp
+```
+
+---
+
+## Performance Tuning
+
+### Multiple Workers
+
+For production deployments with higher load:
+
+```bash
+# Using CLI (if supported)
+uv run nextcloud-mcp-server --workers 4
+
+# Using uvicorn
+uv run uvicorn nextcloud_mcp_server.app:get_app \
+  --factory \
+  --workers 4 \
+  --host 0.0.0.0 \
+  --port 8000
+```
+
+### Production Settings
+
+```bash
+# Recommended production configuration
+uv run nextcloud-mcp-server \
+  --oauth \
+  --host 127.0.0.1 \
+  --port 8000 \
+  --log-level warning \
+  --transport streamable-http \
+  --workers 2
+```
+
+---
+
+## Troubleshooting
+
+### Server won't start
+
+Check logs for errors:
+```bash
+uv run nextcloud-mcp-server --log-level debug
+```
+
+Common issues:
+- Environment variables not loaded - See [Configuration](configuration.md#loading-environment-variables)
+- Port already in use - Try a different port with `--port`
+- OAuth configuration errors - See [Troubleshooting](troubleshooting.md)
+
+### Can't connect to server
+
+1. Verify server is running: `curl http://localhost:8000/health`
+2. Check firewall settings
+3. Verify host binding (use `0.0.0.0` to allow network access)
+4. Check OAuth authentication if enabled
+
+### OAuth authentication fails
+
+See [Troubleshooting OAuth](troubleshooting.md) for detailed OAuth troubleshooting.
+
+---
+
+## See Also
+
+- [Configuration Guide](configuration.md) - Environment variables
+- [OAuth Setup](oauth-setup.md) - OAuth authentication setup
+- [Troubleshooting](troubleshooting.md) - Common issues and solutions
+- [Installation](installation.md) - Installing the server

docs/troubleshooting.md

@@ -0,0 +1,556 @@
+# Troubleshooting
+
+This guide covers common issues and solutions for the Nextcloud MCP server.
+
+> **OAuth-specific issues?** See the dedicated [OAuth Troubleshooting Guide](oauth-troubleshooting.md) for OAuth authentication problems, OIDC discovery issues, token validation failures, and more.
+
+## OAuth Issues (Quick Reference)
+
+### Issue: "OAuth mode requires NEXTCLOUD_HOST environment variable"
+
+**Cause:** The `NEXTCLOUD_HOST` environment variable is not set or empty.
+
+**Solution:**
+
+```bash
+# Ensure NEXTCLOUD_HOST is set in your .env file
+echo "NEXTCLOUD_HOST=https://your.nextcloud.instance.com" >> .env
+
+# Load environment variables
+export $(grep -v '^#' .env | xargs)
+
+# Verify it's set
+echo $NEXTCLOUD_HOST
+```
+
+---
+
+### Issue: "OAuth mode requires either client credentials OR dynamic client registration"
+
+**Cause:** The required Nextcloud OIDC apps are either:
+1. Not installed (both `oidc` and `user_oidc` apps are required)
+2. Don't have dynamic client registration enabled
+3. Aren't providing a registration endpoint
+
+**Solution:**
+
+**Option 1: Enable dynamic client registration**
+
+1. Verify **both** OIDC apps are installed:
+   - Navigate to Nextcloud **Apps** → **Security**
+   - Install **"OIDC"** (OIDC Identity Provider app) if not present
+   - Install **"OpenID Connect user backend"** (user_oidc app) if not present
+
+2. Enable dynamic client registration:
+   - Go to **Settings** → **OIDC** (Administration)
+   - Enable "Allow dynamic client registration"
+
+3. Configure Bearer token validation:
+   ```bash
+   # Required for user_oidc app to validate tokens
+   php occ config:system:set user_oidc oidc_provider_bearer_validation --value=true --type=boolean
+   ```
+
+3. Verify the registration endpoint exists:
+   ```bash
+   curl https://your.nextcloud.instance.com/.well-known/openid-configuration | jq '.registration_endpoint'
+   # Should output: "https://your.nextcloud.instance.com/apps/oidc/register"
+   ```
+
+**Option 2: Provide pre-configured credentials**
+
+Register a client and add credentials to `.env`:
+
+```bash
+# On your Nextcloud server
+php occ oidc:create \
+  --name="Nextcloud MCP Server" \
+  --type=confidential \
+  --redirect-uri="http://localhost:8000/oauth/callback"
+
+# Add to .env
+echo "NEXTCLOUD_OIDC_CLIENT_ID=<from-output>" >> .env
+echo "NEXTCLOUD_OIDC_CLIENT_SECRET=<from-output>" >> .env
+```
+
+See [OAuth Setup Guide](oauth-setup.md) for detailed instructions.
+
+---
+
+### Issue: "Stored client has expired"
+
+**Cause:** Dynamically registered OAuth clients expire (default: 1 hour).
+
+**Solution:**
+
+**Option 1: Restart the server** (automatic re-registration)
+
+```bash
+# Server checks credentials at startup and re-registers if expired
+uv run nextcloud-mcp-server --oauth
+```
+
+**Option 2: Use pre-configured credentials** (recommended for production)
+
+```bash
+# Register permanent client via Nextcloud CLI
+php occ oidc:create \
+  --name="Nextcloud MCP Server" \
+  --type=confidential \
+  --redirect-uri="http://localhost:8000/oauth/callback"
+
+# Add to .env
+NEXTCLOUD_OIDC_CLIENT_ID=<from-output>
+NEXTCLOUD_OIDC_CLIENT_SECRET=<from-output>
+```
+
+**Option 3: Increase expiration time**
+
+```bash
+# Via Nextcloud occ command (default: 3600 seconds)
+php occ config:app:set oidc expire_time --value "86400"  # 24 hours
+```
+
+---
+
+### Issue: "HTTP 401 Unauthorized" when calling Nextcloud APIs
+
+**Cause:** OAuth Bearer tokens may not work with certain Nextcloud endpoints due to session handling in the CORS middleware.
+
+**Background:** The `user_oidc` app's CORS middleware interferes with Bearer token authentication for non-OCS endpoints (like Notes API). This affects app-specific APIs but not OCS APIs.
+
+**Solution:**
+
+A patch for the `user_oidc` app is required to fix Bearer token support. See [oauth2-bearer-token-session-issue.md](oauth2-bearer-token-session-issue.md) for:
+- Detailed explanation of the issue
+- Patch to apply to the `user_oidc` app
+- Link to upstream pull request
+
+**Affected endpoints:**
+- Notes API (`/apps/notes/api/`)
+- Other app-specific endpoints
+
+**Unaffected endpoints:**
+- OCS APIs (`/ocs/v2.php/`)
+- Capabilities endpoint
+
+---
+
+### Issue: "Permission denied" when reading/writing OAuth client credentials file
+
+**Cause:** The server cannot access the OAuth client storage file (default: `.nextcloud_oauth_client.json`).
+
+**Solution:**
+
+```bash
+# Check file permissions
+ls -la .nextcloud_oauth_client.json
+
+# Fix file permissions (should be 0600 - owner read/write only)
+chmod 600 .nextcloud_oauth_client.json
+
+# Ensure the directory is writable
+chmod 755 $(dirname .nextcloud_oauth_client.json)
+
+# If the file doesn't exist, ensure the directory is writable so it can be created
+mkdir -p $(dirname .nextcloud_oauth_client.json)
+```
+
+---
+
+### Issue: "OIDC discovery failed" or "Cannot reach OIDC discovery endpoint"
+
+**Cause:** The server cannot reach the Nextcloud OIDC discovery endpoint.
+
+**Solution:**
+
+1. Verify the Nextcloud URL is correct:
+   ```bash
+   echo $NEXTCLOUD_HOST
+   # Should be the full URL: https://your.nextcloud.instance.com
+   ```
+
+2. Test the discovery endpoint manually:
+   ```bash
+   curl https://your.nextcloud.instance.com/.well-known/openid-configuration
+   # Should return JSON with OIDC configuration
+   ```
+
+3. Check network connectivity:
+   ```bash
+   ping your.nextcloud.instance.com
+   ```
+
+4. Verify **both** OIDC apps are installed and enabled in Nextcloud:
+   - `oidc` - OIDC Identity Provider
+   - `user_oidc` - OpenID Connect user backend
+
+5. Check firewall rules if using Docker
+
+---
+
+### Switching Between OAuth and BasicAuth
+
+#### To switch from BasicAuth to OAuth:
+
+```bash
+# 1. Remove or comment out USERNAME/PASSWORD in .env
+sed -i 's/^NEXTCLOUD_USERNAME/#NEXTCLOUD_USERNAME/' .env
+sed -i 's/^NEXTCLOUD_PASSWORD/#NEXTCLOUD_PASSWORD/' .env
+
+# 2. Ensure NEXTCLOUD_HOST is set
+grep NEXTCLOUD_HOST .env
+
+# 3. Restart server with OAuth
+export $(grep -v '^#' .env | xargs)
+uv run nextcloud-mcp-server --oauth
+```
+
+#### To switch from OAuth to BasicAuth:
+
+```bash
+# 1. Add USERNAME/PASSWORD to .env
+echo "NEXTCLOUD_USERNAME=your-username" >> .env
+echo "NEXTCLOUD_PASSWORD=your-password" >> .env
+
+# 2. Restart server (BasicAuth auto-detected, or use --no-oauth)
+export $(grep -v '^#' .env | xargs)
+uv run nextcloud-mcp-server --no-oauth
+```
+
+---
+
+### For More OAuth Help
+
+See the dedicated **[OAuth Troubleshooting Guide](oauth-troubleshooting.md)** for:
+- Bearer token authentication failures
+- PKCE validation errors
+- Token validation issues
+- Client registration problems
+- Advanced OAuth debugging
+- And much more...
+
+---
+
+## Configuration Issues
+
+### Issue: Environment variables not loaded
+
+**Cause:** Environment variables from `.env` file are not loaded into the shell.
+
+**Solution:**
+
+**On Linux/macOS:**
+```bash
+# Load all variables from .env
+export $(grep -v '^#' .env | xargs)
+
+# Verify variables are set
+env | grep NEXTCLOUD
+```
+
+**On Windows (PowerShell):**
+```powershell
+# Load variables from .env
+Get-Content .env | ForEach-Object {
+    if ($_ -match '^\s*([^#][^=]*)\s*=\s*(.*)$') {
+        [Environment]::SetEnvironmentVariable($matches[1].Trim(), $matches[2].Trim(), "Process")
+    }
+}
+
+# Verify variables are set
+Get-ChildItem Env:NEXTCLOUD*
+```
+
+**With Docker:**
+```bash
+# Docker automatically loads .env when using --env-file
+docker run -p 127.0.0.1:8000:8000 --env-file .env --rm \
+  ghcr.io/cbcoutinho/nextcloud-mcp-server:latest
+```
+
+---
+
+### Issue: ".env file not found"
+
+**Cause:** The `.env` file doesn't exist or is in the wrong location.
+
+**Solution:**
+
+```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
+```
+
+---
+
+### Issue: "Invalid Nextcloud credentials"
+
+**Cause:** BasicAuth credentials are incorrect or the app password has been revoked.
+
+**Solution:**
+
+1. **Verify username:**
+   ```bash
+   # Username should match your Nextcloud login
+   echo $NEXTCLOUD_USERNAME
+   ```
+
+2. **Generate a new app password:**
+   - Log in to Nextcloud
+   - Go to **Settings** → **Security**
+   - Under "Devices & sessions", create a new app password
+   - Update `.env` with the new password
+
+3. **Test credentials manually:**
+   ```bash
+   curl -u "$NEXTCLOUD_USERNAME:$NEXTCLOUD_PASSWORD" \
+     "$NEXTCLOUD_HOST/ocs/v2.php/cloud/capabilities" \
+     -H "OCS-APIRequest: true"
+   # Should return XML with capabilities
+   ```
+
+---
+
+## Server Issues
+
+### Issue: "Address already in use" / Port conflict
+
+**Cause:** Another process is using port 8000.
+
+**Solution:**
+
+**Option 1: Use a different port**
+```bash
+uv run nextcloud-mcp-server --port 8080
+```
+
+**Option 2: Find and kill the process using the port**
+```bash
+# On Linux/macOS
+lsof -ti:8000 | xargs kill -9
+
+# On Windows
+netstat -ano | findstr :8000
+taskkill /PID <pid> /F
+```
+
+**Option 3: Stop other MCP server instances**
+```bash
+# Check for running instances
+ps aux | grep nextcloud-mcp-server
+
+# Kill specific process
+kill <pid>
+```
+
+---
+
+### Issue: Server starts but can't connect
+
+**Cause:** Server is bound to localhost only, or firewall is blocking connections.
+
+**Solution:**
+
+1. **Check server binding:**
+   ```bash
+   # Bind to all interfaces to allow network access
+   uv run nextcloud-mcp-server --host 0.0.0.0 --port 8000
+   ```
+
+2. **Test connectivity:**
+   ```bash
+   # Test from same machine
+   curl http://localhost:8000/health
+
+   # Test from network (if using --host 0.0.0.0)
+   curl http://<server-ip>:8000/health
+   ```
+
+3. **Check firewall:**
+   ```bash
+   # Linux (ufw)
+   sudo ufw allow 8000/tcp
+
+   # Linux (firewalld)
+   sudo firewall-cmd --add-port=8000/tcp --permanent
+   sudo firewall-cmd --reload
+   ```
+
+---
+
+### Issue: Server crashes or restarts frequently
+
+**Cause:** Various issues including memory limits, uncaught exceptions, or OAuth token expiration.
+
+**Solution:**
+
+1. **Check logs with debug level:**
+   ```bash
+   uv run nextcloud-mcp-server --log-level debug
+   ```
+
+2. **Monitor resource usage:**
+   ```bash
+   # Check memory and CPU
+   top -p $(pgrep -f nextcloud-mcp-server)
+   ```
+
+3. **Use process manager for automatic restart:**
+   ```bash
+   # With systemd (see Running guide for full config)
+   sudo systemctl restart nextcloud-mcp
+
+   # With Docker Compose (includes restart: unless-stopped)
+   docker-compose up -d
+   ```
+
+4. **Check for OAuth credential expiration** (if using dynamic registration):
+   - See ["Stored client has expired"](#issue-stored-client-has-expired) above
+
+---
+
+## Connection Issues
+
+### Issue: MCP client can't authenticate
+
+**Cause:** OAuth flow failing or credentials invalid.
+
+**Solution:**
+
+**For OAuth:**
+1. Verify OAuth is configured correctly:
+   ```bash
+   uv run nextcloud-mcp-server --oauth --log-level debug
+   # Look for "OAuth initialization complete"
+   ```
+
+2. Check that OIDC app is accessible:
+   ```bash
+   curl https://your.nextcloud.instance.com/.well-known/openid-configuration
+   ```
+
+3. Verify MCP_SERVER_URL matches your setup:
+   ```bash
+   echo $NEXTCLOUD_MCP_SERVER_URL
+   # Should match the URL clients use to connect
+   ```
+
+**For BasicAuth:**
+1. Verify credentials work:
+   ```bash
+   curl -u "$NEXTCLOUD_USERNAME:$NEXTCLOUD_PASSWORD" \
+     "$NEXTCLOUD_HOST/ocs/v2.php/cloud/capabilities" \
+     -H "OCS-APIRequest: true"
+   ```
+
+---
+
+### Issue: Tools return errors or don't work
+
+**Cause:** Missing Nextcloud apps, incorrect permissions, or API issues.
+
+**Solution:**
+
+1. **Verify required Nextcloud apps are installed:**
+   - Notes: Install "Notes" app
+   - Calendar: Ensure CalDAV is enabled
+   - Contacts: Ensure CardDAV is enabled
+   - Deck: Install "Deck" app
+
+2. **Check user permissions:**
+   - Ensure the authenticated user has access to the resources
+   - Check sharing permissions for shared resources
+
+3. **Test API directly:**
+   ```bash
+   # Test Notes API
+   curl -u "$NEXTCLOUD_USERNAME:$NEXTCLOUD_PASSWORD" \
+     "$NEXTCLOUD_HOST/apps/notes/api/v1/notes"
+
+   # Test with OAuth Bearer token
+   curl -H "Authorization: Bearer $TOKEN" \
+     "$NEXTCLOUD_HOST/apps/notes/api/v1/notes"
+   ```
+
+4. **Check server logs for specific errors:**
+   ```bash
+   uv run nextcloud-mcp-server --log-level debug
+   ```
+
+---
+
+## Getting Help
+
+If you continue to experience issues:
+
+### 1. Enable Debug Logging
+
+```bash
+uv run nextcloud-mcp-server --log-level debug
+```
+
+Review the logs for specific error messages.
+
+### 2. Verify OIDC Configuration (OAuth mode)
+
+```bash
+# Check OIDC discovery
+curl https://your.nextcloud.instance.com/.well-known/openid-configuration
+
+# Check registration endpoint exists
+curl https://your.nextcloud.instance.com/.well-known/openid-configuration | jq '.registration_endpoint'
+```
+
+### 3. Test Nextcloud API Access
+
+```bash
+# Test OCS API (should work with OAuth)
+curl -H "Authorization: Bearer $TOKEN" \
+  "$NEXTCLOUD_HOST/ocs/v2.php/cloud/capabilities?format=json" \
+  -H "OCS-APIRequest: true"
+
+# Test app API (may need patch - see oauth2-bearer-token-session-issue.md)
+curl -H "Authorization: Bearer $TOKEN" \
+  "$NEXTCLOUD_HOST/apps/notes/api/v1/notes"
+```
+
+### 4. Check Versions
+
+```bash
+# MCP Server version
+uv run nextcloud-mcp-server --version
+
+# Python version
+python3 --version
+
+# Nextcloud version (check in admin panel)
+```
+
+### 5. Open an Issue
+
+If problems persist, open an issue on the [GitHub repository](https://github.com/cbcoutinho/nextcloud-mcp-server/issues) with:
+
+- **Server logs** (with `--log-level debug`)
+- **Nextcloud version**
+- **OIDC app version** (if using OAuth)
+- **Error messages**
+- **Steps to reproduce**
+- **Environment details** (OS, Python version, Docker vs local)
+
+---
+
+## See Also
+
+- **[OAuth Troubleshooting](oauth-troubleshooting.md)** - Dedicated OAuth troubleshooting guide
+- [OAuth Setup Guide](oauth-setup.md) - OAuth configuration
+- [OAuth Architecture](oauth-architecture.md) - How OAuth works
+- [Upstream Status](oauth-upstream-status.md) - Required patches and upstream PRs
+- [Configuration](configuration.md) - Environment variables
+- [Running the Server](running.md) - Server options

env.sample

@@ -1,3 +1,23 @@
+# Nextcloud Instance
 NEXTCLOUD_HOST=
+
+# ===== AUTHENTICATION MODE =====
+# Choose ONE of the following:
+
+# Option 1: OAuth2/OIDC (RECOMMENDED - More Secure)
+# - Requires Nextcloud OIDC app installed and configured
+# - Admin must enable "Dynamic Client Registration" in OIDC app settings
+# - Leave NEXTCLOUD_USERNAME and NEXTCLOUD_PASSWORD empty to use OAuth mode
+# - Optional: Pre-register client and provide credentials (otherwise auto-registers)
+NEXTCLOUD_OIDC_CLIENT_ID=
+NEXTCLOUD_OIDC_CLIENT_SECRET=
+NEXTCLOUD_OIDC_CLIENT_STORAGE=.nextcloud_oauth_client.json
+NEXTCLOUD_MCP_SERVER_URL=http://localhost:8000
+
+# Option 2: Basic Authentication (LEGACY - Less Secure)
+# - Requires username and password
+# - Credentials stored in environment variables
+# - Use only for backward compatibility or if OAuth unavailable
+# - If these are set, OAuth mode is disabled
 NEXTCLOUD_USERNAME=
 NEXTCLOUD_PASSWORD=

nextcloud_mcp_server/app.py

@@ -1,62 +1,374 @@
-import click
 import logging
-import uvicorn
+import os
 from collections.abc import AsyncIterator
-from contextlib import asynccontextmanager, AsyncExitStack
+from contextlib import AsyncExitStack, asynccontextmanager
 from dataclasses import dataclass
 
+import click
+import uvicorn
+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.routing import Mount
 
-from mcp.server.fastmcp import Context, FastMCP
-
-from nextcloud_mcp_server.config import setup_logging
+from nextcloud_mcp_server.auth import NextcloudTokenVerifier, load_or_register_client
 from nextcloud_mcp_server.client import NextcloudClient
+from nextcloud_mcp_server.config import setup_logging
+from nextcloud_mcp_server.context import get_client as get_nextcloud_client
 from nextcloud_mcp_server.server import (
     configure_calendar_tools,
     configure_contacts_tools,
+    configure_deck_tools,
     configure_notes_tools,
+    configure_sharing_tools,
     configure_tables_tools,
     configure_webdav_tools,
-    configure_deck_tools,
 )
 
-
 logger = logging.getLogger(__name__)
 
 
+def validate_pkce_support(discovery: dict, discovery_url: str) -> None:
+    """
+    Validate that the OIDC provider properly advertises PKCE support.
+
+    According to RFC 8414, if code_challenge_methods_supported is absent,
+    it means the authorization server does not support PKCE.
+
+    MCP clients require PKCE with S256 and will refuse to connect if this
+    field is missing or doesn't include S256.
+    """
+
+    code_challenge_methods = discovery.get("code_challenge_methods_supported")
+
+    if code_challenge_methods is None:
+        click.echo("=" * 80, err=True)
+        click.echo(
+            "ERROR: OIDC CONFIGURATION ERROR - Missing PKCE Support Advertisement",
+            err=True,
+        )
+        click.echo("=" * 80, err=True)
+        click.echo(f"Discovery URL: {discovery_url}", err=True)
+        click.echo("", err=True)
+        click.echo(
+            "The OIDC discovery document is missing 'code_challenge_methods_supported'.",
+            err=True,
+        )
+        click.echo(
+            "According to RFC 8414, this means the server does NOT support PKCE.",
+            err=True,
+        )
+        click.echo("", err=True)
+        click.echo("⚠️  MCP clients (like Claude Code) WILL REJECT this provider!")
+        click.echo("", err=True)
+        click.echo("How to fix:", err=True)
+        click.echo(
+            "  1. Ensure PKCE is enabled in Nextcloud OIDC app settings", err=True
+        )
+        click.echo(
+            "  2. Update the OIDC app to advertise PKCE support in discovery", err=True
+        )
+        click.echo("  3. See: RFC 8414 Section 2 (Authorization Server Metadata)")
+        click.echo("=" * 80, err=True)
+        click.echo("", err=True)
+        return
+
+    if "S256" not in code_challenge_methods:
+        click.echo("=" * 80, err=True)
+        click.echo(
+            "WARNING: OIDC CONFIGURATION WARNING - S256 Challenge Method Not Advertised",
+            err=True,
+        )
+        click.echo("=" * 80, err=True)
+        click.echo(f"Discovery URL: {discovery_url}", err=True)
+        click.echo(f"Advertised methods: {code_challenge_methods}", err=True)
+        click.echo("", err=True)
+        click.echo("MCP specification requires S256 code challenge method.", err=True)
+        click.echo("Some clients may reject this provider.", err=True)
+        click.echo("=" * 80, err=True)
+        click.echo("", err=True)
+        return
+
+    click.echo(f"✓ PKCE support validated: {code_challenge_methods}")
+
+
 @dataclass
 class AppContext:
+    """Application context for BasicAuth mode."""
+
     client: NextcloudClient
 
 
+@dataclass
+class OAuthAppContext:
+    """Application context for OAuth mode."""
+
+    nextcloud_host: str
+    token_verifier: NextcloudTokenVerifier
+
+
+def is_oauth_mode() -> bool:
+    """
+    Determine if OAuth mode should be used.
+
+    OAuth mode is enabled when:
+    - NEXTCLOUD_USERNAME and NEXTCLOUD_PASSWORD are NOT set
+    - Or explicitly enabled via configuration
+
+    Returns:
+        True if OAuth mode, False if BasicAuth mode
+    """
+    username = os.getenv("NEXTCLOUD_USERNAME")
+    password = os.getenv("NEXTCLOUD_PASSWORD")
+
+    # If both username and password are set, use BasicAuth
+    if username and password:
+        logger.info(
+            "BasicAuth mode detected (NEXTCLOUD_USERNAME and NEXTCLOUD_PASSWORD set)"
+        )
+        return False
+
+    logger.info("OAuth mode detected (NEXTCLOUD_USERNAME/PASSWORD not set)")
+    return True
+
+
 @asynccontextmanager
-async def app_lifespan(server: FastMCP) -> AsyncIterator[AppContext]:
-    """Manage application lifecycle with type-safe context"""
-    # Initialize on startup
-    logging.info("Creating Nextcloud client")
+async def app_lifespan_basic(server: FastMCP) -> AsyncIterator[AppContext]:
+    """
+    Manage application lifecycle for BasicAuth mode.
+
+    Creates a single Nextcloud client with basic authentication
+    that is shared across all requests.
+    """
+    logger.info("Starting MCP server in BasicAuth mode")
+    logger.info("Creating Nextcloud client with BasicAuth")
+
     client = NextcloudClient.from_env()
-    logging.info("Client initialization wait complete.")
+    logger.info("Client initialization complete")
+
     try:
         yield AppContext(client=client)
     finally:
-        # Cleanup on shutdown
+        logger.info("Shutting down BasicAuth mode")
         await client.close()
 
 
+@asynccontextmanager
+async def app_lifespan_oauth(server: FastMCP) -> AsyncIterator[OAuthAppContext]:
+    """
+    Manage application lifecycle for OAuth mode.
+
+    Initializes OAuth client registration and token verifier.
+    Does NOT create a Nextcloud client - clients are created per-request.
+    """
+    logger.info("Starting MCP server in OAuth mode")
+
+    nextcloud_host = os.getenv("NEXTCLOUD_HOST")
+    if not nextcloud_host:
+        raise ValueError("NEXTCLOUD_HOST environment variable is required")
+
+    nextcloud_host = nextcloud_host.rstrip("/")
+
+    # Get OAuth discovery endpoint
+    discovery_url = f"{nextcloud_host}/.well-known/openid-configuration"
+
+    try:
+        # Fetch OIDC discovery
+        import httpx
+
+        async with httpx.AsyncClient() as client:
+            response = await client.get(discovery_url)
+            response.raise_for_status()
+            discovery = response.json()
+
+        logger.info(f"OIDC discovery successful: {discovery_url}")
+
+        # Extract endpoints
+        userinfo_uri = discovery["userinfo_endpoint"]
+        registration_endpoint = discovery.get("registration_endpoint")
+
+        logger.info(f"Userinfo endpoint: {userinfo_uri}")
+
+        # Handle client registration
+        client_id = os.getenv("NEXTCLOUD_OIDC_CLIENT_ID")
+        client_secret = os.getenv("NEXTCLOUD_OIDC_CLIENT_SECRET")
+        storage_path = os.getenv(
+            "NEXTCLOUD_OIDC_CLIENT_STORAGE", ".nextcloud_oauth_client.json"
+        )
+
+        if client_id and client_secret:
+            logger.info("Using pre-configured OAuth client credentials")
+        elif registration_endpoint:
+            logger.info("Dynamic client registration available")
+            mcp_server_url = os.getenv(
+                "NEXTCLOUD_MCP_SERVER_URL", "http://localhost:8000"
+            )
+            redirect_uris = [f"{mcp_server_url}/oauth/callback"]
+
+            # Load or register client
+            client_info = await load_or_register_client(
+                nextcloud_url=nextcloud_host,
+                registration_endpoint=registration_endpoint,
+                storage_path=storage_path,
+                client_name="Nextcloud MCP Server",
+                redirect_uris=redirect_uris,
+            )
+
+            logger.info(f"OAuth client ready: {client_info.client_id[:16]}...")
+        else:
+            raise ValueError(
+                "OAuth mode requires either:\n"
+                "1. NEXTCLOUD_OIDC_CLIENT_ID and NEXTCLOUD_OIDC_CLIENT_SECRET, OR\n"
+                "2. Dynamic client registration enabled on Nextcloud OIDC app"
+            )
+
+        # Create token verifier
+        token_verifier = NextcloudTokenVerifier(
+            nextcloud_host=nextcloud_host, userinfo_uri=userinfo_uri
+        )
+
+        logger.info("OAuth initialization complete")
+
+        try:
+            yield OAuthAppContext(
+                nextcloud_host=nextcloud_host, token_verifier=token_verifier
+            )
+        finally:
+            logger.info("Shutting down OAuth mode")
+            await token_verifier.close()
+
+    except Exception as e:
+        logger.error(f"Failed to initialize OAuth mode: {e}")
+        raise
+
+
+async def setup_oauth_config():
+    """
+    Setup OAuth configuration by performing OIDC discovery and client registration.
+
+    This is done synchronously before FastMCP initialization because FastMCP
+    requires token_verifier at construction time.
+
+    Returns:
+        Tuple of (nextcloud_host, token_verifier, auth_settings)
+    """
+    nextcloud_host = os.getenv("NEXTCLOUD_HOST")
+    if not nextcloud_host:
+        raise ValueError(
+            "NEXTCLOUD_HOST environment variable is required for OAuth mode"
+        )
+
+    nextcloud_host = nextcloud_host.rstrip("/")
+    discovery_url = f"{nextcloud_host}/.well-known/openid-configuration"
+
+    logger.info(f"Performing OIDC discovery: {discovery_url}")
+
+    # Fetch OIDC discovery
+    import httpx
+
+    async with httpx.AsyncClient() as client:
+        response = await client.get(discovery_url)
+        response.raise_for_status()
+        discovery = response.json()
+
+    logger.info("OIDC discovery successful")
+
+    # Validate PKCE support
+    validate_pkce_support(discovery, discovery_url)
+
+    # Extract endpoints
+    issuer = discovery["issuer"]
+    userinfo_uri = discovery["userinfo_endpoint"]
+    registration_endpoint = discovery.get("registration_endpoint")
+
+    # Allow override of public issuer URL for clients
+    # (useful when MCP server accesses Nextcloud via internal URL
+    # but needs to advertise a different URL to clients)
+    public_issuer = os.getenv("NEXTCLOUD_PUBLIC_ISSUER_URL")
+    if public_issuer:
+        public_issuer = public_issuer.rstrip("/")
+        logger.info(f"Using public issuer URL for clients: {public_issuer}")
+        issuer = public_issuer
+
+    # Handle client registration
+    client_id = os.getenv("NEXTCLOUD_OIDC_CLIENT_ID")
+    client_secret = os.getenv("NEXTCLOUD_OIDC_CLIENT_SECRET")
+
+    if client_id and client_secret:
+        logger.info("Using pre-configured OAuth client credentials")
+    elif registration_endpoint:
+        logger.info("Dynamic client registration available")
+        storage_path = os.getenv(
+            "NEXTCLOUD_OIDC_CLIENT_STORAGE", ".nextcloud_oauth_client.json"
+        )
+        mcp_server_url = os.getenv("NEXTCLOUD_MCP_SERVER_URL", "http://localhost:8000")
+        redirect_uris = [f"{mcp_server_url}/oauth/callback"]
+
+        # Load or register client
+        client_info = await load_or_register_client(
+            nextcloud_url=nextcloud_host,
+            registration_endpoint=registration_endpoint,
+            storage_path=storage_path,
+            client_name="Nextcloud MCP Server",
+            redirect_uris=redirect_uris,
+        )
+
+        logger.info(f"OAuth client ready: {client_info.client_id[:16]}...")
+    else:
+        raise ValueError(
+            "OAuth mode requires either:\n"
+            "1. NEXTCLOUD_OIDC_CLIENT_ID and NEXTCLOUD_OIDC_CLIENT_SECRET, OR\n"
+            "2. Dynamic client registration enabled on Nextcloud OIDC app"
+        )
+
+    # Create token verifier
+    token_verifier = NextcloudTokenVerifier(
+        nextcloud_host=nextcloud_host, userinfo_uri=userinfo_uri
+    )
+
+    # Create auth settings
+    mcp_server_url = os.getenv("NEXTCLOUD_MCP_SERVER_URL", "http://localhost:8000")
+    auth_settings = AuthSettings(
+        issuer_url=AnyHttpUrl(issuer),
+        resource_server_url=AnyHttpUrl(mcp_server_url),
+        required_scopes=["openid", "profile"],
+    )
+
+    logger.info("OAuth configuration complete")
+
+    return nextcloud_host, token_verifier, auth_settings
+
+
 def get_app(transport: str = "sse", enabled_apps: list[str] | None = None):
     setup_logging()
 
-    # Create an MCP server
-    mcp = FastMCP("Nextcloud MCP", lifespan=app_lifespan)
+    # Determine authentication mode
+    oauth_enabled = is_oauth_mode()
+
+    if oauth_enabled:
+        logger.info("Configuring MCP server for OAuth mode")
+        # Asynchronously get the OAuth configuration
+        import asyncio
+
+        nextcloud_host, token_verifier, auth_settings = asyncio.run(
+            setup_oauth_config()
+        )
+        mcp = FastMCP(
+            "Nextcloud MCP",
+            lifespan=app_lifespan_oauth,
+            token_verifier=token_verifier,
+            auth=auth_settings,
+        )
+    else:
+        logger.info("Configuring MCP server for BasicAuth mode")
+        mcp = FastMCP("Nextcloud MCP", lifespan=app_lifespan_basic)
 
     @mcp.resource("nc://capabilities")
     async def nc_get_capabilities():
         """Get the Nextcloud Host capabilities"""
-        ctx: Context = (
-            mcp.get_context()
-        )  # https://github.com/modelcontextprotocol/python-sdk/issues/244
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        ctx: Context = mcp.get_context()
+        client = get_nextcloud_client(ctx)
         return await client.capabilities()
 
     # Define available apps and their configuration functions
@@ -64,6 +376,7 @@ def get_app(transport: str = "sse", enabled_apps: list[str] | None = None):
         "notes": configure_notes_tools,
         "tables": configure_tables_tools,
         "webdav": configure_webdav_tools,
+        "sharing": configure_sharing_tools,
         "calendar": configure_calendar_tools,
         "contacts": configure_contacts_tools,
         "deck": configure_deck_tools,
@@ -86,7 +399,7 @@ def get_app(transport: str = "sse", enabled_apps: list[str] | None = None):
     if transport == "sse":
         mcp_app = mcp.sse_app()
         lifespan = None
-    else:
+    elif transport in ("http", "streamable-http"):
         mcp_app = mcp.streamable_http_app()
 
         @asynccontextmanager
@@ -101,23 +414,31 @@ def get_app(transport: str = "sse", enabled_apps: list[str] | None = None):
 
 
 @click.command()
-@click.option("--host", "-h", default="127.0.0.1", show_default=True)
-@click.option("--port", "-p", type=int, default=8000, show_default=True)
-@click.option("--workers", "-w", type=int, default=None)
-@click.option("--reload", "-r", is_flag=True)
+@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(
+    "--workers", "-w", type=int, default=None, help="Number of worker processes"
+)
+@click.option("--reload", "-r", is_flag=True, help="Enable auto-reload")
 @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"]),
+    type=click.Choice(["sse", "streamable-http", "http"]),
+    help="MCP transport protocol",
 )
 @click.option(
     "--enable-app",
@@ -126,6 +447,35 @@ def get_app(transport: str = "sse", enabled_apps: list[str] | None = None):
     type=click.Choice(["notes", "tables", "webdav", "calendar", "contacts", "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(
+    "--oauth-storage-path",
+    envvar="NEXTCLOUD_OIDC_CLIENT_STORAGE",
+    default=".nextcloud_oauth_client.json",
+    show_default=True,
+    help="Path to store OAuth client credentials (can also use NEXTCLOUD_OIDC_CLIENT_STORAGE 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)",
+)
 def run(
     host: str,
     port: int,
@@ -134,7 +484,107 @@ def run(
     log_level: str,
     transport: str,
     enable_app: tuple[str, ...],
+    oauth: bool | None,
+    oauth_client_id: str | None,
+    oauth_client_secret: str | None,
+    oauth_storage_path: str,
+    mcp_server_url: str,
 ):
+    """
+    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 (legacy)
+      $ nextcloud-mcp-server --host 0.0.0.0 --port 8000
+
+      # OAuth mode with auto-registration
+      $ nextcloud-mcp-server --oauth
+
+      # OAuth mode with pre-configured client
+      $ nextcloud-mcp-server --oauth --oauth-client-id=xxx --oauth-client-secret=yyy
+    """
+    # Set OAuth env vars from CLI options if provided
+    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_storage_path:
+        os.environ["NEXTCLOUD_OIDC_CLIENT_STORAGE"] = oauth_storage_path
+    if mcp_server_url:
+        os.environ["NEXTCLOUD_MCP_SERVER_URL"] = mcp_server_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: "
+                + os.getenv(
+                    "NEXTCLOUD_OIDC_CLIENT_STORAGE", ".nextcloud_oauth_client.json"
+                ),
+                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
 
     if reload or workers:

nextcloud_mcp_server/auth/__init__.py

@@ -0,0 +1,14 @@
+"""OAuth authentication components for Nextcloud MCP server."""
+
+from .bearer_auth import BearerAuth
+from .client_registration import load_or_register_client, register_client
+from .context_helper import get_client_from_context
+from .token_verifier import NextcloudTokenVerifier
+
+__all__ = [
+    "BearerAuth",
+    "NextcloudTokenVerifier",
+    "register_client",
+    "load_or_register_client",
+    "get_client_from_context",
+]

nextcloud_mcp_server/auth/bearer_auth.py

@@ -0,0 +1,34 @@
+"""Bearer token authentication for httpx."""
+
+from httpx import Auth, Request
+
+
+class BearerAuth(Auth):
+    """
+    Bearer token authentication flow for httpx.
+
+    This auth class adds the Authorization: Bearer <token> header
+    to all outgoing requests.
+    """
+
+    def __init__(self, token: str):
+        """
+        Initialize bearer authentication.
+
+        Args:
+            token: The bearer token to use for authentication
+        """
+        self.token = token
+
+    def auth_flow(self, request: Request):
+        """
+        Add Authorization header to the request.
+
+        Args:
+            request: The outgoing HTTP request
+
+        Yields:
+            The modified request with Authorization header
+        """
+        request.headers["Authorization"] = f"Bearer {self.token}"
+        yield request

nextcloud_mcp_server/auth/client_registration.py

@@ -0,0 +1,260 @@
+"""Dynamic client registration for Nextcloud OIDC."""
+
+import json
+import logging
+import os
+import time
+from pathlib import Path
+from typing import Any
+
+import httpx
+
+logger = logging.getLogger(__name__)
+
+
+class ClientInfo:
+    """Client registration information."""
+
+    def __init__(
+        self,
+        client_id: str,
+        client_secret: str,
+        client_id_issued_at: int,
+        client_secret_expires_at: int,
+        redirect_uris: list[str],
+    ):
+        self.client_id = client_id
+        self.client_secret = client_secret
+        self.client_id_issued_at = client_id_issued_at
+        self.client_secret_expires_at = client_secret_expires_at
+        self.redirect_uris = redirect_uris
+
+    @property
+    def is_expired(self) -> bool:
+        """Check if the client has expired."""
+        return time.time() >= self.client_secret_expires_at
+
+    @property
+    def expires_soon(self) -> bool:
+        """Check if client expires within 5 minutes."""
+        return time.time() >= (self.client_secret_expires_at - 300)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary for storage."""
+        return {
+            "client_id": self.client_id,
+            "client_secret": self.client_secret,
+            "client_id_issued_at": self.client_id_issued_at,
+            "client_secret_expires_at": self.client_secret_expires_at,
+            "redirect_uris": self.redirect_uris,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "ClientInfo":
+        """Create from dictionary."""
+        return cls(
+            client_id=data["client_id"],
+            client_secret=data["client_secret"],
+            client_id_issued_at=data["client_id_issued_at"],
+            client_secret_expires_at=data["client_secret_expires_at"],
+            redirect_uris=data["redirect_uris"],
+        )
+
+
+async def register_client(
+    nextcloud_url: str,
+    registration_endpoint: str,
+    client_name: str = "Nextcloud MCP Server",
+    redirect_uris: list[str] | None = None,
+    scopes: str = "openid profile email",
+) -> ClientInfo:
+    """
+    Register a new OAuth client with Nextcloud OIDC using dynamic client registration.
+
+    Args:
+        nextcloud_url: Base URL of the Nextcloud instance
+        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
+
+    Returns:
+        ClientInfo with registration details
+
+    Raises:
+        httpx.HTTPStatusError: If registration fails
+        ValueError: If response is invalid
+    """
+    if redirect_uris is None:
+        redirect_uris = ["http://localhost:8000/oauth/callback"]
+
+    client_metadata = {
+        "client_name": client_name,
+        "redirect_uris": redirect_uris,
+        "token_endpoint_auth_method": "client_secret_post",
+        "grant_types": ["authorization_code", "refresh_token"],
+        "response_types": ["code"],
+        "scope": scopes,
+    }
+
+    logger.info(f"Registering OAuth client with Nextcloud: {client_name}")
+    logger.debug(f"Registration endpoint: {registration_endpoint}")
+
+    async with httpx.AsyncClient(timeout=30.0) as client:
+        try:
+            response = await client.post(
+                registration_endpoint,
+                json=client_metadata,
+                headers={"Content-Type": "application/json"},
+            )
+            response.raise_for_status()
+
+            client_info = response.json()
+            logger.info(
+                f"Successfully registered client: {client_info.get('client_id')}"
+            )
+            logger.info(
+                f"Client expires at: {client_info.get('client_secret_expires_at')} "
+                f"(in {client_info.get('client_secret_expires_at', 0) - int(time.time())} seconds)"
+            )
+
+            return ClientInfo(
+                client_id=client_info["client_id"],
+                client_secret=client_info["client_secret"],
+                client_id_issued_at=client_info.get(
+                    "client_id_issued_at", int(time.time())
+                ),
+                client_secret_expires_at=client_info.get(
+                    "client_secret_expires_at", int(time.time()) + 3600
+                ),
+                redirect_uris=client_info.get("redirect_uris", redirect_uris),
+            )
+
+        except httpx.HTTPStatusError as e:
+            logger.error(f"Failed to register client: HTTP {e.response.status_code}")
+            logger.error(f"Response: {e.response.text}")
+            raise
+        except KeyError as e:
+            logger.error(f"Invalid response from registration endpoint: missing {e}")
+            raise ValueError(f"Invalid registration response: missing {e}")
+
+
+def load_client_from_file(storage_path: Path) -> ClientInfo | None:
+    """
+    Load client credentials from storage file.
+
+    Args:
+        storage_path: Path to the JSON file containing client credentials
+
+    Returns:
+        ClientInfo if file exists and is valid, None otherwise
+    """
+    if not storage_path.exists():
+        logger.debug(f"Client storage file not found: {storage_path}")
+        return None
+
+    try:
+        with open(storage_path, "r") as f:
+            data = json.load(f)
+
+        client_info = ClientInfo.from_dict(data)
+
+        if client_info.is_expired:
+            logger.warning(
+                f"Stored client has expired (expired at {client_info.client_secret_expires_at})"
+            )
+            return None
+
+        logger.info(f"Loaded client from storage: {client_info.client_id[:16]}...")
+        if client_info.expires_soon:
+            logger.warning("Client expires soon (within 5 minutes)")
+
+        return client_info
+
+    except (json.JSONDecodeError, KeyError, ValueError) as e:
+        logger.error(f"Failed to load client from file: {e}")
+        return None
+
+
+def save_client_to_file(client_info: ClientInfo, storage_path: Path):
+    """
+    Save client credentials to storage file.
+
+    Args:
+        client_info: Client information to save
+        storage_path: Path to save the JSON file
+
+    Raises:
+        OSError: If file cannot be written
+    """
+    try:
+        # Create directory if it doesn't exist
+        storage_path.parent.mkdir(parents=True, exist_ok=True)
+
+        # Write client info
+        with open(storage_path, "w") as f:
+            json.dump(client_info.to_dict(), f, indent=2)
+
+        # Set restrictive permissions (owner read/write only)
+        os.chmod(storage_path, 0o600)
+
+        logger.info(f"Saved client credentials to {storage_path}")
+
+    except OSError as e:
+        logger.error(f"Failed to save client credentials: {e}")
+        raise
+
+
+async def load_or_register_client(
+    nextcloud_url: str,
+    registration_endpoint: str,
+    storage_path: str | Path,
+    client_name: str = "Nextcloud MCP Server",
+    redirect_uris: list[str] | None = None,
+    force_register: bool = True,
+) -> ClientInfo:
+    """
+    Load client from storage or register a new one if not found/expired.
+
+    This function:
+    1. Checks for existing client credentials in storage
+    2. Validates the credentials are not expired
+    3. Registers a new client if needed
+    4. Saves the new client credentials
+
+    Args:
+        nextcloud_url: Base URL of the Nextcloud instance
+        registration_endpoint: Full URL to the registration endpoint
+        storage_path: Path to store client credentials
+        client_name: Name of the client application
+        redirect_uris: List of redirect URIs
+        force_register: Force registration even if valid credentials exist
+
+    Returns:
+        ClientInfo with valid credentials
+
+    Raises:
+        httpx.HTTPStatusError: If registration fails
+        ValueError: If response is invalid
+    """
+    storage_path = Path(storage_path)
+
+    # Try to load existing client unless forced to register
+    if not force_register:
+        client_info = load_client_from_file(storage_path)
+        if client_info:
+            return client_info
+
+    # Register new client
+    logger.info("Registering new OAuth client...")
+    client_info = await register_client(
+        nextcloud_url=nextcloud_url,
+        registration_endpoint=registration_endpoint,
+        client_name=client_name,
+        redirect_uris=redirect_uris,
+    )
+
+    # Save to storage
+    save_client_to_file(client_info, storage_path)
+
+    return client_info

nextcloud_mcp_server/auth/context_helper.py

@@ -0,0 +1,65 @@
+"""Helper functions for extracting OAuth context from MCP requests."""
+
+import logging
+
+from mcp.server.auth.provider import AccessToken
+from mcp.server.fastmcp import Context
+
+from ..client import NextcloudClient
+
+logger = logging.getLogger(__name__)
+
+
+def get_client_from_context(ctx: Context, base_url: str) -> NextcloudClient:
+    """
+    Extract authenticated user context from MCP request and create NextcloudClient.
+
+    This function retrieves the OAuth access token from the MCP context,
+    extracts the username from the token's resource field (where we stored it
+    during token verification), and creates a NextcloudClient with bearer auth.
+
+    Args:
+        ctx: MCP request context containing session info
+        base_url: Nextcloud base URL
+
+    Returns:
+        NextcloudClient configured with bearer token auth
+
+    Raises:
+        AttributeError: If context doesn't contain expected OAuth session data
+        ValueError: If username cannot be extracted from token
+    """
+    try:
+        # In Starlette with FastMCP OAuth, the authenticated user info is stored in request.user
+        # The FastMCP auth middleware sets request.user to an AuthenticatedUser object
+        # which contains the access_token
+        if hasattr(ctx.request_context.request, "user") and hasattr(
+            ctx.request_context.request.user, "access_token"
+        ):
+            access_token: AccessToken = ctx.request_context.request.user.access_token
+            logger.debug("Retrieved access token from request.user for OAuth request")
+        else:
+            logger.error(
+                "OAuth authentication failed: No access token found in request"
+            )
+            raise AttributeError("No access token found in OAuth request context")
+
+        # Extract username from resource field (RFC 8707)
+        # We stored the username here during token verification
+        username = access_token.resource
+
+        if not username:
+            logger.error("No username found in access token resource field")
+            raise ValueError("Username not available in OAuth token context")
+
+        logger.debug(f"Creating OAuth NextcloudClient for user: {username}")
+
+        # Create client with bearer token
+        return NextcloudClient.from_token(
+            base_url=base_url, token=access_token.token, username=username
+        )
+
+    except AttributeError as e:
+        logger.error(f"Failed to extract OAuth context: {e}")
+        logger.error("This may indicate the server is not running in OAuth mode")
+        raise

nextcloud_mcp_server/auth/token_verifier.py

@@ -0,0 +1,207 @@
+"""Token verification using Nextcloud OIDC userinfo endpoint."""
+
+import logging
+import time
+from typing import Any
+
+import httpx
+from mcp.server.auth.provider import AccessToken, TokenVerifier
+
+logger = logging.getLogger(__name__)
+
+
+class NextcloudTokenVerifier(TokenVerifier):
+    """
+    Validates access tokens using Nextcloud OIDC userinfo endpoint.
+
+    This verifier:
+    1. Calls the userinfo endpoint with the bearer token
+    2. Caches successful responses to avoid repeated API calls
+    3. Extracts username from the 'sub' or 'preferred_username' claim
+    4. Optionally supports JWT validation for performance (future enhancement)
+
+    The userinfo endpoint validates the token and returns user claims if valid,
+    or returns HTTP 400/401 if the token is invalid or expired.
+    """
+
+    def __init__(
+        self,
+        nextcloud_host: str,
+        userinfo_uri: str,
+        cache_ttl: int = 3600,
+    ):
+        """
+        Initialize the token verifier.
+
+        Args:
+            nextcloud_host: Base URL of the Nextcloud instance (e.g., https://cloud.example.com)
+            userinfo_uri: Full URL to the userinfo endpoint
+            cache_ttl: Time-to-live for cached tokens in seconds (default: 3600)
+        """
+        self.nextcloud_host = nextcloud_host.rstrip("/")
+        self.userinfo_uri = userinfo_uri
+        self.cache_ttl = cache_ttl
+
+        # Cache: token -> (userinfo, expiry_timestamp)
+        self._token_cache: dict[str, tuple[dict[str, Any], float]] = {}
+
+        # HTTP client for userinfo requests
+        self._client = httpx.AsyncClient(timeout=10.0)
+
+    async def verify_token(self, token: str) -> AccessToken | None:
+        """
+        Verify a bearer token by calling the userinfo endpoint.
+
+        This method:
+        1. Checks the cache first for recent validations
+        2. Calls the userinfo endpoint if not cached
+        3. Returns AccessToken with username stored in metadata
+
+        Args:
+            token: The bearer token to verify
+
+        Returns:
+            AccessToken if valid, None if invalid or expired
+        """
+        # Check cache first
+        cached = self._get_cached_token(token)
+        if cached:
+            logger.debug("Token found in cache")
+            return cached
+
+        # Validate via userinfo endpoint
+        try:
+            return await self._verify_via_userinfo(token)
+        except Exception as e:
+            logger.warning(f"Token verification failed: {e}")
+            return None
+
+    async def _verify_via_userinfo(self, token: str) -> AccessToken | None:
+        """
+        Validate token by calling the userinfo endpoint.
+
+        Args:
+            token: The bearer token to verify
+
+        Returns:
+            AccessToken if valid, None otherwise
+        """
+        try:
+            response = await self._client.get(
+                self.userinfo_uri, headers={"Authorization": f"Bearer {token}"}
+            )
+
+            if response.status_code == 200:
+                userinfo = response.json()
+                logger.debug(
+                    f"Token validated successfully for user: {userinfo.get('sub')}"
+                )
+
+                # Cache the result
+                expiry = time.time() + self.cache_ttl
+                self._token_cache[token] = (userinfo, expiry)
+
+                # Create AccessToken with username in resource field (workaround for MCP SDK)
+                username = userinfo.get("sub") or userinfo.get("preferred_username")
+                if not username:
+                    logger.error("No username found in userinfo response")
+                    return None
+
+                return AccessToken(
+                    token=token,
+                    client_id="",  # Not available from userinfo
+                    scopes=self._extract_scopes(userinfo),
+                    expires_at=int(expiry),
+                    resource=username,  # Store username in resource field (RFC 8707)
+                )
+
+            elif response.status_code in (400, 401, 403):
+                logger.info(f"Token validation failed: HTTP {response.status_code}")
+                return None
+            else:
+                logger.warning(
+                    f"Unexpected response from userinfo: {response.status_code}"
+                )
+                return None
+
+        except httpx.TimeoutException:
+            logger.error("Timeout while validating token via userinfo endpoint")
+            return None
+        except httpx.RequestError as e:
+            logger.error(f"Network error while validating token: {e}")
+            return None
+        except Exception as e:
+            logger.error(f"Unexpected error during token validation: {e}")
+            return None
+
+    def _get_cached_token(self, token: str) -> AccessToken | None:
+        """
+        Retrieve a token from cache if not expired.
+
+        Args:
+            token: The bearer token to look up
+
+        Returns:
+            AccessToken if cached and valid, None otherwise
+        """
+        if token not in self._token_cache:
+            return None
+
+        userinfo, expiry = self._token_cache[token]
+
+        # Check if expired
+        if time.time() >= expiry:
+            logger.debug("Cached token expired, removing from cache")
+            del self._token_cache[token]
+            return None
+
+        # Return cached AccessToken
+        username = userinfo.get("sub") or userinfo.get("preferred_username")
+        return AccessToken(
+            token=token,
+            client_id="",
+            scopes=self._extract_scopes(userinfo),
+            expires_at=int(expiry),
+            resource=username,
+        )
+
+    def _extract_scopes(self, userinfo: dict[str, Any]) -> list[str]:
+        """
+        Extract scopes from userinfo response.
+
+        Since the userinfo response doesn't include the original scopes,
+        we infer them from the claims present in the response.
+
+        Args:
+            userinfo: The userinfo response dictionary
+
+        Returns:
+            List of inferred scopes
+        """
+        scopes = ["openid"]  # Always present
+
+        if "email" in userinfo:
+            scopes.append("email")
+
+        if any(
+            key in userinfo for key in ["name", "given_name", "family_name", "picture"]
+        ):
+            scopes.append("profile")
+
+        if "roles" in userinfo:
+            scopes.append("roles")
+
+        if "groups" in userinfo:
+            scopes.append("groups")
+
+        return scopes
+
+    def clear_cache(self):
+        """Clear the token cache."""
+        self._token_cache.clear()
+        logger.debug("Token cache cleared")
+
+    async def close(self):
+        """Cleanup resources."""
+        await self._client.aclose()
+        logger.debug("Token verifier closed")

nextcloud_mcp_server/client/__init__.py

@@ -2,22 +2,25 @@ import logging
 import os
 
 from httpx import (
+    AsyncBaseTransport,
     AsyncClient,
+    AsyncHTTPTransport,
     Auth,
     BasicAuth,
     Request,
     Response,
-    AsyncBaseTransport,
-    AsyncHTTPTransport,
 )
 
 from ..controllers.notes_search import NotesSearchController
 from .calendar import CalendarClient
 from .contacts import ContactsClient
 from .deck import DeckClient
+from .groups import GroupsClient
 from .notes import NotesClient
+from .sharing import SharingClient
 from .tables import TablesClient
 from .webdav import WebDAVClient
+from .users import UsersClient
 
 logger = logging.getLogger(__name__)
 
@@ -71,6 +74,9 @@ class NextcloudClient:
         self.calendar = CalendarClient(self._client, username)
         self.contacts = ContactsClient(self._client, username)
         self.deck = DeckClient(self._client, username)
+        self.users = UsersClient(self._client, username)
+        self.groups = GroupsClient(self._client, username)
+        self.sharing = SharingClient(self._client, username)
 
         # Initialize controllers
         self._notes_search = NotesSearchController()
@@ -85,6 +91,23 @@ class NextcloudClient:
         # Pass username to constructor
         return cls(base_url=host, username=username, auth=BasicAuth(username, password))
 
+    @classmethod
+    def from_token(cls, base_url: str, token: str, username: str):
+        """Create NextcloudClient with OAuth bearer token.
+
+        Args:
+            base_url: Nextcloud base URL
+            token: OAuth access token
+            username: Nextcloud username
+
+        Returns:
+            NextcloudClient configured with bearer token authentication
+        """
+        from ..auth import BearerAuth
+
+        logger.info(f"Creating NC Client for user '{username}' using OAuth token")
+        return cls(base_url=base_url, username=username, auth=BearerAuth(token))
+
     async def capabilities(self):
         response = await self._client.get(
             "/ocs/v2.php/cloud/capabilities",

nextcloud_mcp_server/client/base.py

@@ -1,11 +1,11 @@
 """Base client for Nextcloud operations with shared authentication."""
 
 import logging
-from abc import ABC
-
-from functools import wraps
 import time
-from httpx import HTTPStatusError, codes, RequestError, AsyncClient
+from abc import ABC
+from functools import wraps
+
+from httpx import AsyncClient, HTTPStatusError, RequestError, codes
 
 logger = logging.getLogger(__name__)
 

nextcloud_mcp_server/client/contacts.py

@@ -1,10 +1,12 @@
 """CardDAV client for NextCloud contacts operations."""
 
 import logging
-from .base import BaseNextcloudClient
 import xml.etree.ElementTree as ET
+
 from pythonvCard4.vcard import Contact
 
+from .base import BaseNextcloudClient
+
 logger = logging.getLogger(__name__)
 
 

nextcloud_mcp_server/client/deck.py

@@ -1,16 +1,16 @@
-from typing import List, Optional, Dict, Any
+from typing import Any, Dict, List, Optional
 
 from nextcloud_mcp_server.client.base import BaseNextcloudClient
 from nextcloud_mcp_server.models.deck import (
-    DeckBoard,
-    DeckStack,
-    DeckCard,
-    DeckLabel,
     DeckACL,
     DeckAttachment,
+    DeckBoard,
+    DeckCard,
     DeckComment,
-    DeckSession,
     DeckConfig,
+    DeckLabel,
+    DeckSession,
+    DeckStack,
 )
 
 
@@ -99,7 +99,7 @@ class DeckClient(BaseNextcloudClient):
         permission_edit: bool,
         permission_share: bool,
         permission_manage: bool,
-    ) -> List[DeckACL]:
+    ) -> DeckACL:
         json_data = {
             "type": type,
             "participant": participant,
@@ -107,10 +107,14 @@ class DeckClient(BaseNextcloudClient):
             "permissionShare": permission_share,
             "permissionManage": permission_manage,
         }
+        headers = self._get_deck_headers()
         response = await self._make_request(
-            "POST", f"/apps/deck/api/v1.0/boards/{board_id}/acl", json=json_data
+            "POST",
+            f"/apps/deck/api/v1.0/boards/{board_id}/acl",
+            json=json_data,
+            headers=headers,
         )
-        return [DeckACL(**acl) for acl in response.json()]
+        return DeckACL(**response.json())
 
     async def update_acl_rule(
         self,
@@ -127,13 +131,20 @@ class DeckClient(BaseNextcloudClient):
             json_data["permissionShare"] = permission_share
         if permission_manage is not None:
             json_data["permissionManage"] = permission_manage
+        headers = self._get_deck_headers()
         await self._make_request(
-            "PUT", f"/apps/deck/api/v1.0/boards/{board_id}/acl/{acl_id}", json=json_data
+            "PUT",
+            f"/apps/deck/api/v1.0/boards/{board_id}/acl/{acl_id}",
+            json=json_data,
+            headers=headers,
         )
 
     async def delete_acl_rule(self, board_id: int, acl_id: int) -> None:
+        headers = self._get_deck_headers()
         await self._make_request(
-            "DELETE", f"/apps/deck/api/v1.0/boards/{board_id}/acl/{acl_id}"
+            "DELETE",
+            f"/apps/deck/api/v1.0/boards/{board_id}/acl/{acl_id}",
+            headers=headers,
         )
 
     async def clone_board(

nextcloud_mcp_server/client/groups.py

@@ -0,0 +1,151 @@
+"""Nextcloud Groups API client."""
+
+import logging
+from typing import List
+
+from .base import BaseNextcloudClient, retry_on_429
+
+logger = logging.getLogger(__name__)
+
+
+class GroupsClient(BaseNextcloudClient):
+    """Client for Nextcloud Groups API operations."""
+
+    @retry_on_429
+    async def search_groups(
+        self,
+        search: str | None = None,
+        limit: int | None = None,
+        offset: int | None = None,
+    ) -> List[str]:
+        """
+        Search for groups on the Nextcloud server.
+
+        Args:
+            search: Optional search string to filter groups
+            limit: Optional limit for number of results
+            offset: Optional offset for pagination
+
+        Returns:
+            List of group IDs matching the search criteria
+        """
+        params = {}
+        if search is not None:
+            params["search"] = search
+        if limit is not None:
+            params["limit"] = limit
+        if offset is not None:
+            params["offset"] = offset
+
+        response = await self._client.get(
+            "/ocs/v2.php/cloud/groups",
+            params=params,
+            headers={"OCS-APIRequest": "true", "Accept": "application/json"},
+        )
+        response.raise_for_status()
+        data = response.json()
+
+        groups = data["ocs"]["data"].get("groups", [])
+        return groups
+
+    @retry_on_429
+    async def create_group(self, groupid: str) -> None:
+        """
+        Create a new group.
+
+        Args:
+            groupid: The group ID to create
+
+        Raises:
+            HTTPStatusError: If the request fails (e.g., group already exists)
+        """
+        response = await self._client.post(
+            "/ocs/v2.php/cloud/groups",
+            data={"groupid": groupid},
+            headers={"OCS-APIRequest": "true", "Accept": "application/json"},
+        )
+        response.raise_for_status()
+        logger.info(f"Created group: {groupid}")
+
+    @retry_on_429
+    async def delete_group(self, groupid: str) -> None:
+        """
+        Delete a group.
+
+        Args:
+            groupid: The group ID to delete
+
+        Raises:
+            HTTPStatusError: If the request fails (e.g., group doesn't exist)
+        """
+        response = await self._client.delete(
+            f"/ocs/v2.php/cloud/groups/{groupid}",
+            headers={"OCS-APIRequest": "true", "Accept": "application/json"},
+        )
+        response.raise_for_status()
+        logger.info(f"Deleted group: {groupid}")
+
+    @retry_on_429
+    async def get_group_members(self, groupid: str) -> List[str]:
+        """
+        Get members of a group.
+
+        Args:
+            groupid: The group ID
+
+        Returns:
+            List of usernames in the group
+        """
+        response = await self._client.get(
+            f"/ocs/v2.php/cloud/groups/{groupid}",
+            headers={"OCS-APIRequest": "true", "Accept": "application/json"},
+        )
+        response.raise_for_status()
+        data = response.json()
+
+        users = data["ocs"]["data"].get("users", [])
+        return users
+
+    @retry_on_429
+    async def get_group_subadmins(self, groupid: str) -> List[str]:
+        """
+        Get subadmins of a group.
+
+        Args:
+            groupid: The group ID
+
+        Returns:
+            List of usernames who are subadmins of the group
+        """
+        response = await self._client.get(
+            f"/ocs/v2.php/cloud/groups/{groupid}/subadmins",
+            headers={"OCS-APIRequest": "true", "Accept": "application/json"},
+        )
+        response.raise_for_status()
+        data = response.json()
+
+        # The API returns data as a list or dict depending on results
+        subadmins_data = data["ocs"]["data"]
+        if isinstance(subadmins_data, list):
+            return subadmins_data
+        return []
+
+    @retry_on_429
+    async def update_group_displayname(self, groupid: str, displayname: str) -> None:
+        """
+        Update a group's display name.
+
+        Args:
+            groupid: The group ID
+            displayname: The new display name
+
+        Raises:
+            HTTPStatusError: If the request fails
+        """
+        response = await self._client.put(
+            f"/ocs/v2.php/cloud/groups/{groupid}",
+            data={"key": "displayname", "value": displayname},
+            headers={"OCS-APIRequest": "true", "Accept": "application/json"},
+        )
+        response.raise_for_status()
+        logger.info(f"Updated group {groupid} displayname to: {displayname}")

nextcloud_mcp_server/client/sharing.py

@@ -0,0 +1,208 @@
+"""Nextcloud OCS Sharing API client for file/folder sharing operations."""
+
+import logging
+from typing import Any
+
+from .base import BaseNextcloudClient, retry_on_429
+
+logger = logging.getLogger(__name__)
+
+
+class SharingClient(BaseNextcloudClient):
+    """Client for Nextcloud OCS Sharing API operations."""
+
+    @retry_on_429
+    async def create_share(
+        self,
+        path: str,
+        share_with: str,
+        share_type: int = 0,
+        permissions: int = 1,
+    ) -> dict[str, Any]:
+        """Create a share for a file or folder.
+
+        Args:
+            path: Path to file/folder to share (relative to user's files)
+            share_with: Username (for user share) or group name (for group share)
+            share_type: Share type (0=user, 1=group, 3=public link)
+            permissions: Share permissions:
+                - 1 = read
+                - 2 = update
+                - 4 = create
+                - 8 = delete
+                - 16 = share
+                - 31 = all permissions
+                Common combinations: 1 (read-only), 3 (read+update), 15 (read+update+create+delete)
+
+        Returns:
+            Share data including share ID
+
+        Raises:
+            HTTPStatusError: If the request fails
+        """
+        response = await self._client.post(
+            "/ocs/v2.php/apps/files_sharing/api/v1/shares",
+            headers={"OCS-APIRequest": "true", "Accept": "application/json"},
+            data={
+                "path": path,
+                "shareType": share_type,
+                "shareWith": share_with,
+                "permissions": permissions,
+            },
+        )
+        response.raise_for_status()
+        data = response.json()
+
+        # OCS API v2 uses HTTP-style status codes (200 for success)
+        # OCS API v1 used custom codes (100 for success)
+        ocs_status = data["ocs"]["meta"]["statuscode"]
+        if ocs_status not in (100, 200):
+            ocs_message = data["ocs"]["meta"].get("message", "Unknown error")
+            raise RuntimeError(f"OCS API error (code {ocs_status}): {ocs_message}")
+
+        share_data = data["ocs"]["data"]
+
+        # Handle case where data might be an empty list on error
+        if not share_data or (isinstance(share_data, list) and len(share_data) == 0):
+            ocs_message = data["ocs"]["meta"].get("message", "Unknown error")
+            raise RuntimeError(
+                f"Share creation failed: {ocs_message} (status {ocs_status})"
+            )
+
+        logger.info(
+            f"Created share {share_data['id']}: {path} -> {share_with} "
+            f"(type={share_type}, permissions={permissions})"
+        )
+        return share_data
+
+    @retry_on_429
+    async def delete_share(self, share_id: int) -> None:
+        """Delete a share by its ID.
+
+        Args:
+            share_id: The share ID to delete
+
+        Raises:
+            HTTPStatusError: If the request fails
+        """
+        response = await self._client.delete(
+            f"/ocs/v2.php/apps/files_sharing/api/v1/shares/{share_id}",
+            headers={"OCS-APIRequest": "true", "Accept": "application/json"},
+        )
+        response.raise_for_status()
+        data = response.json()
+
+        if data["ocs"]["meta"]["statuscode"] not in (100, 200):
+            raise RuntimeError(
+                f"OCS API error: {data['ocs']['meta'].get('message', 'Unknown error')}"
+            )
+
+        logger.info(f"Deleted share {share_id}")
+
+    @retry_on_429
+    async def get_share(self, share_id: int) -> dict[str, Any]:
+        """Get information about a specific share.
+
+        Args:
+            share_id: The share ID
+
+        Returns:
+            Share data
+
+        Raises:
+            HTTPStatusError: If the request fails
+        """
+        response = await self._client.get(
+            f"/ocs/v2.php/apps/files_sharing/api/v1/shares/{share_id}",
+            headers={"OCS-APIRequest": "true", "Accept": "application/json"},
+        )
+        response.raise_for_status()
+        data = response.json()
+
+        if data["ocs"]["meta"]["statuscode"] not in (100, 200):
+            raise RuntimeError(
+                f"OCS API error: {data['ocs']['meta'].get('message', 'Unknown error')}"
+            )
+
+        share_data = data["ocs"]["data"]
+        # The API returns a list with a single share, extract the first element
+        if isinstance(share_data, list) and len(share_data) > 0:
+            return share_data[0]
+        return share_data
+
+    @retry_on_429
+    async def list_shares(
+        self, path: str | None = None, shared_with_me: bool = False
+    ) -> list[dict[str, Any]]:
+        """List shares.
+
+        Args:
+            path: Optional path to filter shares for a specific file/folder
+            shared_with_me: If True, list shares shared with the current user
+
+        Returns:
+            List of share data
+
+        Raises:
+            HTTPStatusError: If the request fails
+        """
+        params = {}
+        if path:
+            params["path"] = path
+        if shared_with_me:
+            params["shared_with_me"] = "true"
+
+        response = await self._client.get(
+            "/ocs/v2.php/apps/files_sharing/api/v1/shares",
+            params=params,
+            headers={"OCS-APIRequest": "true", "Accept": "application/json"},
+        )
+        response.raise_for_status()
+        data = response.json()
+
+        if data["ocs"]["meta"]["statuscode"] not in (100, 200):
+            raise RuntimeError(
+                f"OCS API error: {data['ocs']['meta'].get('message', 'Unknown error')}"
+            )
+
+        # Handle both single share and list of shares
+        shares_data = data["ocs"]["data"]
+        if isinstance(shares_data, dict):
+            return [shares_data]
+        return shares_data if shares_data else []
+
+    @retry_on_429
+    async def update_share(
+        self, share_id: int, permissions: int | None = None
+    ) -> dict[str, Any]:
+        """Update a share's permissions.
+
+        Args:
+            share_id: The share ID to update
+            permissions: New permissions value (see create_share for values)
+
+        Returns:
+            Updated share data
+
+        Raises:
+            HTTPStatusError: If the request fails
+        """
+        data = {}
+        if permissions is not None:
+            data["permissions"] = permissions
+
+        response = await self._client.put(
+            f"/ocs/v2.php/apps/files_sharing/api/v1/shares/{share_id}",
+            headers={"OCS-APIRequest": "true", "Accept": "application/json"},
+            data=data,
+        )
+        response.raise_for_status()
+        result = response.json()
+
+        if result["ocs"]["meta"]["statuscode"] not in (100, 200):
+            raise RuntimeError(
+                f"OCS API error: {result['ocs']['meta'].get('message', 'Unknown error')}"
+            )
+
+        logger.info(f"Updated share {share_id}")
+        return result["ocs"]["data"]

nextcloud_mcp_server/client/users.py

@@ -0,0 +1,222 @@
+from typing import List, Optional, Dict
+from nextcloud_mcp_server.client.base import BaseNextcloudClient
+from nextcloud_mcp_server.models.users import UserDetails
+
+
+class UsersClient(BaseNextcloudClient):
+    """Client for Nextcloud User API operations."""
+
+    def _get_user_headers(
+        self, additional_headers: Optional[Dict[str, str]] = None
+    ) -> Dict[str, str]:
+        """Get standard headers required for User API calls."""
+        headers = {"OCS-APIRequest": "true", "Accept": "application/json"}
+        if additional_headers:
+            headers.update(additional_headers)
+        return headers
+
+    async def create_user(
+        self,
+        userid: str,
+        password: Optional[str] = None,
+        display_name: Optional[str] = None,
+        email: Optional[str] = None,
+        groups: Optional[List[str]] = None,
+        subadmin_groups: Optional[List[str]] = None,
+        quota: Optional[str] = None,
+        language: Optional[str] = None,
+    ) -> None:
+        """
+        Create a new user on the Nextcloud server.
+        """
+        data = {"userid": userid}
+        if password is not None:
+            data["password"] = password
+        if display_name is not None:
+            data["displayName"] = display_name
+        if email is not None:
+            data["email"] = email
+        if groups is not None:
+            for i, group in enumerate(groups):
+                data[f"groups[{i}]"] = group
+        if subadmin_groups is not None:
+            for i, group in enumerate(subadmin_groups):
+                data[f"subadmin[{i}]"] = group
+        if quota is not None:
+            data["quota"] = quota
+        if language is not None:
+            data["language"] = language
+
+        headers = self._get_user_headers()
+        await self._make_request(
+            "POST", "/ocs/v2.php/cloud/users", data=data, headers=headers
+        )
+
+    async def search_users(
+        self,
+        search: Optional[str] = None,
+        limit: Optional[int] = None,
+        offset: Optional[int] = None,
+    ) -> List[str]:
+        """
+        Retrieves a list of users from the Nextcloud server.
+        """
+        params = {}
+        if search is not None:
+            params["search"] = search
+        if limit is not None:
+            params["limit"] = limit
+        if offset is not None:
+            params["offset"] = offset
+
+        headers = self._get_user_headers()
+        response = await self._make_request(
+            "GET", "/ocs/v2.php/cloud/users", params=params, headers=headers
+        )
+        # The v2 API returns JSON with users as a direct list under data.users
+        data = response.json()["ocs"]["data"]
+        return data.get("users", [])
+
+    async def get_user_details(self, userid: str) -> UserDetails:
+        """
+        Retrieves information about a single user.
+        """
+        headers = self._get_user_headers()
+        response = await self._make_request(
+            "GET", f"/ocs/v2.php/cloud/users/{userid}", headers=headers
+        )
+        return UserDetails(**response.json()["ocs"]["data"])
+
+    async def update_user_field(self, userid: str, key: str, value: str) -> None:
+        """
+        Edits attributes related to a user.
+        """
+        data = {"key": key, "value": value}
+        headers = self._get_user_headers()
+        await self._make_request(
+            "PUT", f"/ocs/v2.php/cloud/users/{userid}", data=data, headers=headers
+        )
+
+    async def get_editable_user_fields(self) -> List[str]:
+        """
+        Gets the list of editable data fields for a user.
+        """
+        headers = self._get_user_headers()
+        response = await self._make_request(
+            "GET", "/ocs/v2.php/cloud/user/fields", headers=headers
+        )
+        # The v2 API returns data as a direct list
+        data = response.json()["ocs"]["data"]
+        return data if isinstance(data, list) else []
+
+    async def disable_user(self, userid: str) -> None:
+        """
+        Disables a user on the Nextcloud server.
+        """
+        headers = self._get_user_headers()
+        await self._make_request(
+            "PUT", f"/ocs/v2.php/cloud/users/{userid}/disable", headers=headers
+        )
+
+    async def enable_user(self, userid: str) -> None:
+        """
+        Enables a user on the Nextcloud server.
+        """
+        headers = self._get_user_headers()
+        await self._make_request(
+            "PUT", f"/ocs/v2.php/cloud/users/{userid}/enable", headers=headers
+        )
+
+    async def delete_user(self, userid: str) -> None:
+        """
+        Deletes a user from the Nextcloud server.
+        """
+        headers = self._get_user_headers()
+        await self._make_request(
+            "DELETE", f"/ocs/v2.php/cloud/users/{userid}", headers=headers
+        )
+
+    async def get_user_groups(self, userid: str) -> List[str]:
+        """
+        Retrieves a list of groups the specified user is a member of.
+        """
+        headers = self._get_user_headers()
+        response = await self._make_request(
+            "GET", f"/ocs/v2.php/cloud/users/{userid}/groups", headers=headers
+        )
+        # The v2 API returns groups as a direct list under data.groups
+        data = response.json()["ocs"]["data"]
+        return data.get("groups", [])
+
+    async def add_user_to_group(self, userid: str, groupid: str) -> None:
+        """
+        Adds the specified user to the specified group.
+        """
+        data = {"groupid": groupid}
+        headers = self._get_user_headers()
+        await self._make_request(
+            "POST",
+            f"/ocs/v2.php/cloud/users/{userid}/groups",
+            data=data,
+            headers=headers,
+        )
+
+    async def remove_user_from_group(self, userid: str, groupid: str) -> None:
+        """
+        Removes the specified user from the specified group.
+        """
+        data = {"groupid": groupid}
+        headers = self._get_user_headers()
+        await self._make_request(
+            "DELETE",
+            f"/ocs/v2.php/cloud/users/{userid}/groups",
+            data=data,
+            headers=headers,
+        )
+
+    async def promote_user_to_subadmin(self, userid: str, groupid: str) -> None:
+        """
+        Makes a user the subadmin of a group.
+        """
+        data = {"groupid": groupid}
+        headers = self._get_user_headers()
+        await self._make_request(
+            "POST",
+            f"/ocs/v2.php/cloud/users/{userid}/subadmins",
+            data=data,
+            headers=headers,
+        )
+
+    async def demote_user_from_subadmin(self, userid: str, groupid: str) -> None:
+        """
+        Removes the subadmin rights for the user specified from the group specified.
+        """
+        data = {"groupid": groupid}
+        headers = self._get_user_headers()
+        await self._make_request(
+            "DELETE",
+            f"/ocs/v2.php/cloud/users/{userid}/subadmins",
+            data=data,
+            headers=headers,
+        )
+
+    async def get_user_subadmin_groups(self, userid: str) -> List[str]:
+        """
+        Returns the groups in which the user is a subadmin.
+        """
+        headers = self._get_user_headers()
+        response = await self._make_request(
+            "GET", f"/ocs/v2.php/cloud/users/{userid}/subadmins", headers=headers
+        )
+        # The v2 API returns data as a direct list
+        data = response.json()["ocs"]["data"]
+        return data if isinstance(data, list) else []
+
+    async def resend_welcome_email(self, userid: str) -> None:
+        """
+        Triggers the welcome email for this user again.
+        """
+        headers = self._get_user_headers()
+        await self._make_request(
+            "POST", f"/ocs/v2.php/cloud/users/{userid}/welcome", headers=headers
+        )

nextcloud_mcp_server/context.py

@@ -0,0 +1,51 @@
+"""Helper functions for accessing context in MCP tools."""
+
+from mcp.server.fastmcp import Context
+
+from nextcloud_mcp_server.client import NextcloudClient
+
+
+def get_client(ctx: Context) -> NextcloudClient:
+    """
+    Get the appropriate Nextcloud client based on authentication mode.
+
+    In BasicAuth mode, returns the shared client from lifespan context.
+    In OAuth mode, creates a new client per-request using the OAuth context.
+
+    This function automatically detects the authentication mode by checking
+    the type of the lifespan context.
+
+    Args:
+        ctx: MCP request context
+
+    Returns:
+        NextcloudClient configured for the current authentication mode
+
+    Raises:
+        AttributeError: If context doesn't contain expected data
+
+    Example:
+        ```python
+        @mcp.tool()
+        async def my_tool(ctx: Context):
+            client = get_client(ctx)
+            return await client.capabilities()
+        ```
+    """
+    lifespan_ctx = ctx.request_context.lifespan_context
+
+    # Try BasicAuth mode first (has 'client' attribute)
+    if hasattr(lifespan_ctx, "client"):
+        return lifespan_ctx.client
+
+    # OAuth mode (has 'nextcloud_host' attribute)
+    if hasattr(lifespan_ctx, "nextcloud_host"):
+        from nextcloud_mcp_server.auth import get_client_from_context
+
+        return get_client_from_context(ctx, lifespan_ctx.nextcloud_host)
+
+    # Unknown context type
+    raise AttributeError(
+        f"Lifespan context does not have 'client' or 'nextcloud_host' attribute. "
+        f"Type: {type(lifespan_ctx)}"
+    )

nextcloud_mcp_server/models/__init__.py

@@ -1,41 +1,25 @@
 """Pydantic models for structured MCP server responses."""
 
 # Base models
-from .base import (
-    BaseResponse,
-    IdResponse,
-    StatusResponse,
-)
-
-# Notes models
-from .notes import (
-    Note,
-    NoteSearchResult,
-    NotesSettings,
-    CreateNoteResponse,
-    UpdateNoteResponse,
-    DeleteNoteResponse,
-    AppendContentResponse,
-    SearchNotesResponse,
-)
+from .base import BaseResponse, IdResponse, StatusResponse
 
 # Calendar models
 from .calendar import (
+    AvailabilitySlot,
+    BulkOperationResponse,
+    BulkOperationResult,
     Calendar,
     CalendarEvent,
     CalendarEventSummary,
     CreateEventResponse,
-    UpdateEventResponse,
-    DeleteEventResponse,
-    ListEventsResponse,
-    ListCalendarsResponse,
-    AvailabilitySlot,
-    FindAvailabilityResponse,
-    BulkOperationResult,
-    BulkOperationResponse,
     CreateMeetingResponse,
-    UpcomingEventsResponse,
+    DeleteEventResponse,
+    FindAvailabilityResponse,
+    ListCalendarsResponse,
+    ListEventsResponse,
     ManageCalendarResponse,
+    UpcomingEventsResponse,
+    UpdateEventResponse,
 )
 
 # Contacts models
@@ -43,38 +27,50 @@ from .contacts import (
     AddressBook,
     Contact,
     ContactField,
+    CreateAddressBookResponse,
+    CreateContactResponse,
+    DeleteAddressBookResponse,
+    DeleteContactResponse,
     ListAddressBooksResponse,
     ListContactsResponse,
-    CreateContactResponse,
     UpdateContactResponse,
-    DeleteContactResponse,
-    CreateAddressBookResponse,
-    DeleteAddressBookResponse,
+)
+
+# Notes models
+from .notes import (
+    AppendContentResponse,
+    CreateNoteResponse,
+    DeleteNoteResponse,
+    Note,
+    NoteSearchResult,
+    NotesSettings,
+    SearchNotesResponse,
+    UpdateNoteResponse,
 )
 
 # Tables models
 from .tables import (
+    CreateRowResponse,
+    DeleteRowResponse,
+    GetSchemaResponse,
+    ListTablesResponse,
+    ReadTableResponse,
     Table,
     TableColumn,
     TableRow,
-    TableView,
     TableSchema,
-    ListTablesResponse,
-    GetSchemaResponse,
-    ReadTableResponse,
-    CreateRowResponse,
+    TableView,
     UpdateRowResponse,
-    DeleteRowResponse,
 )
 
 # WebDAV models
 from .webdav import (
-    FileInfo,
-    DirectoryListing,
-    ReadFileResponse,
-    WriteFileResponse,
     CreateDirectoryResponse,
     DeleteResourceResponse,
+    DirectoryListing,
+    FileInfo,
+    ReadFileResponse,
+    WriteFileResponse,
 )
 
 __all__ = [

nextcloud_mcp_server/models/deck.py

@@ -1,5 +1,5 @@
 from datetime import datetime
-from typing import List, Optional, Dict, Any, Union
+from typing import Any, Dict, List, Optional, Union
 
 from pydantic import BaseModel, Field, field_validator
 

nextcloud_mcp_server/models/users.py

@@ -0,0 +1,40 @@
+from typing import Any, Dict, List, Optional, Union
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class User(BaseModel):
+    """Model for creating a new user."""
+
+    userid: str
+    password: Optional[str] = None
+    displayName: Optional[str] = None
+    email: Optional[str] = None
+    groups: Optional[List[str]] = Field(default_factory=list)
+    subadmin: Optional[List[str]] = Field(default_factory=list)
+    quota: Optional[str] = None
+    language: Optional[str] = None
+
+
+class UserDetails(BaseModel):
+    """Model for retrieving detailed user information."""
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    enabled: bool
+    id: str
+    quota: Union[str, Dict[str, Any]]  # Can be string or quota object
+    email: Optional[str] = None  # Can be null
+    displayname: str = Field(
+        alias="display-name"
+    )  # Handle both displayname and display-name
+    phone: Optional[str] = None
+    address: Optional[str] = None
+    website: Optional[str] = None
+    twitter: Optional[str] = None
+    groups: Optional[List[str]] = Field(default_factory=list)
+
+
+class Group(BaseModel):
+    """Model for a user group."""
+
+    id: str

nextcloud_mcp_server/server/__init__.py

@@ -1,15 +1,17 @@
 from .calendar import configure_calendar_tools
-from .notes import configure_notes_tools
-from .tables import configure_tables_tools
-from .webdav import configure_webdav_tools
 from .contacts import configure_contacts_tools
 from .deck import configure_deck_tools
+from .notes import configure_notes_tools
+from .sharing import configure_sharing_tools
+from .tables import configure_tables_tools
+from .webdav import configure_webdav_tools
 
 __all__ = [
     "configure_calendar_tools",
     "configure_contacts_tools",
     "configure_deck_tools",
     "configure_notes_tools",
+    "configure_sharing_tools",
     "configure_tables_tools",
     "configure_webdav_tools",
 ]

nextcloud_mcp_server/server/calendar.py

@@ -4,11 +4,8 @@ from typing import Optional
 
 from mcp.server.fastmcp import Context, FastMCP
 
-from nextcloud_mcp_server.client import NextcloudClient
-from nextcloud_mcp_server.models.calendar import (
-    Calendar,
-    ListCalendarsResponse,
-)
+from nextcloud_mcp_server.context import get_client
+from nextcloud_mcp_server.models.calendar import Calendar, ListCalendarsResponse
 
 logger = logging.getLogger(__name__)
 
@@ -18,7 +15,7 @@ def configure_calendar_tools(mcp: FastMCP):
     @mcp.tool()
     async def nc_calendar_list_calendars(ctx: Context) -> ListCalendarsResponse:
         """List all available calendars for the user"""
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
         calendars_data = await client.calendar.list_calendars()
 
         calendars = [Calendar(**cal_data) for cal_data in calendars_data]
@@ -74,7 +71,7 @@ def configure_calendar_tools(mcp: FastMCP):
         Returns:
             Dict with event creation result
         """
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
 
         event_data = {
             "title": title,
@@ -133,7 +130,7 @@ def configure_calendar_tools(mcp: FastMCP):
         Returns:
             List of events matching the filters
         """
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
 
         # Convert YYYY-MM-DD format dates to datetime objects
         start_datetime = None
@@ -207,7 +204,7 @@ def configure_calendar_tools(mcp: FastMCP):
         ctx: Context,
     ):
         """Get detailed information about a specific event"""
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
         event_data, etag = await client.calendar.get_event(calendar_name, event_uid)
         return event_data
 
@@ -240,7 +237,7 @@ def configure_calendar_tools(mcp: FastMCP):
         etag: str = "",
     ):
         """Update any aspect of an existing event"""
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
 
         # Build update data with only non-None values
         event_data = {}
@@ -290,7 +287,7 @@ def configure_calendar_tools(mcp: FastMCP):
         ctx: Context,
     ):
         """Delete a calendar event"""
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
         return await client.calendar.delete_event(calendar_name, event_uid)
 
     @mcp.tool()
@@ -332,7 +329,7 @@ def configure_calendar_tools(mcp: FastMCP):
         Returns:
             Dict with meeting creation result
         """
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
 
         # Combine date and time for start_datetime
         start_datetime = f"{date}T{time}:00"
@@ -366,7 +363,7 @@ def configure_calendar_tools(mcp: FastMCP):
         limit: int = 10,
     ):
         """Get upcoming events in next N days"""
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
 
         now = dt.datetime.now()
         end_datetime = now + dt.timedelta(days=days_ahead)
@@ -435,7 +432,7 @@ def configure_calendar_tools(mcp: FastMCP):
         Returns:
             List of available time slots with start/end times and duration
         """
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
 
         # Parse attendees
         attendee_list = []
@@ -536,7 +533,7 @@ def configure_calendar_tools(mcp: FastMCP):
         Returns:
             Summary of operation results including counts and details
         """
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
 
         if operation not in ["update", "delete", "move"]:
             raise ValueError("Operation must be 'update', 'delete', or 'move'")
@@ -758,7 +755,7 @@ def configure_calendar_tools(mcp: FastMCP):
         Returns:
             Result of the calendar management operation
         """
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
 
         if action == "list":
             return await client.calendar.list_calendars()

nextcloud_mcp_server/server/contacts.py

@@ -2,7 +2,7 @@ import logging
 
 from mcp.server.fastmcp import Context, FastMCP
 
-from nextcloud_mcp_server.client import NextcloudClient
+from nextcloud_mcp_server.context import get_client
 
 logger = logging.getLogger(__name__)
 
@@ -12,13 +12,13 @@ def configure_contacts_tools(mcp: FastMCP):
     @mcp.tool()
     async def nc_contacts_list_addressbooks(ctx: Context):
         """List all addressbooks for the user."""
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
         return await client.contacts.list_addressbooks()
 
     @mcp.tool()
     async def nc_contacts_list_contacts(ctx: Context, *, addressbook: str):
         """List all contacts in the specified addressbook."""
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
         return await client.contacts.list_contacts(addressbook=addressbook)
 
     @mcp.tool()
@@ -31,7 +31,7 @@ def configure_contacts_tools(mcp: FastMCP):
             name: The name of the addressbook.
             display_name: The display name of the addressbook.
         """
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
         return await client.contacts.create_addressbook(
             name=name, display_name=display_name
         )
@@ -39,7 +39,7 @@ def configure_contacts_tools(mcp: FastMCP):
     @mcp.tool()
     async def nc_contacts_delete_addressbook(ctx: Context, *, name: str):
         """Delete an addressbook."""
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
         return await client.contacts.delete_addressbook(name=name)
 
     @mcp.tool()
@@ -53,7 +53,7 @@ def configure_contacts_tools(mcp: FastMCP):
             uid: The unique ID for the contact.
             contact_data: A dictionary with the contact's details, e.g. {"fn": "John Doe", "email": "john.doe@example.com"}.
         """
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
         return await client.contacts.create_contact(
             addressbook=addressbook, uid=uid, contact_data=contact_data
         )
@@ -61,7 +61,7 @@ def configure_contacts_tools(mcp: FastMCP):
     @mcp.tool()
     async def nc_contacts_delete_contact(ctx: Context, *, addressbook: str, uid: str):
         """Delete a contact."""
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
         return await client.contacts.delete_contact(addressbook=addressbook, uid=uid)
 
     @mcp.tool()
@@ -76,7 +76,7 @@ def configure_contacts_tools(mcp: FastMCP):
             contact_data: A dictionary with the contact's updated details, e.g. {"fn": "Jane Doe", "email": "jane.doe@example.com"}.
             etag: Optional ETag for optimistic concurrency control.
         """
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
         return await client.contacts.update_contact(
             addressbook=addressbook, uid=uid, contact_data=contact_data, etag=etag
         )

nextcloud_mcp_server/server/deck.py

@@ -3,15 +3,19 @@ from typing import Optional
 
 from mcp.server.fastmcp import Context, FastMCP
 
-from nextcloud_mcp_server.client import NextcloudClient
+from nextcloud_mcp_server.context import get_client
 from nextcloud_mcp_server.models.deck import (
-    CreateBoardResponse,
-    CreateStackResponse,
-    StackOperationResponse,
-    CreateCardResponse,
     CardOperationResponse,
+    CreateBoardResponse,
+    CreateCardResponse,
     CreateLabelResponse,
+    CreateStackResponse,
+    DeckBoard,
+    DeckCard,
+    DeckLabel,
+    DeckStack,
     LabelOperationResponse,
+    StackOperationResponse,
 )
 
 logger = logging.getLogger(__name__)
@@ -25,7 +29,8 @@ def configure_deck_tools(mcp: FastMCP):
     async def deck_boards_resource():
         """List all Nextcloud Deck boards"""
         ctx: Context = mcp.get_context()
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        await ctx.warning("This message is deprecated, use the deck_get_board instead")
+        client = get_client(ctx)
         boards = await client.deck.get_boards()
         return [board.model_dump() for board in boards]
 
@@ -33,7 +38,10 @@ def configure_deck_tools(mcp: FastMCP):
     async def deck_board_resource(board_id: int):
         """Get details of a specific Nextcloud Deck board"""
         ctx: Context = mcp.get_context()
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        await ctx.warning(
+            "This resource is deprecated, use the deck_get_board tool instead"
+        )
+        client = get_client(ctx)
         board = await client.deck.get_board(board_id)
         return board.model_dump()
 
@@ -41,7 +49,10 @@ def configure_deck_tools(mcp: FastMCP):
     async def deck_stacks_resource(board_id: int):
         """List all stacks in a Nextcloud Deck board"""
         ctx: Context = mcp.get_context()
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        await ctx.warning(
+            "This resource is deprecated, use the deck_get_stacks tool instead"
+        )
+        client = get_client(ctx)
         stacks = await client.deck.get_stacks(board_id)
         return [stack.model_dump() for stack in stacks]
 
@@ -49,7 +60,10 @@ def configure_deck_tools(mcp: FastMCP):
     async def deck_stack_resource(board_id: int, stack_id: int):
         """Get details of a specific Nextcloud Deck stack"""
         ctx: Context = mcp.get_context()
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        await ctx.warning(
+            "This resource is deprecated, use the deck_get_stack tool instead"
+        )
+        client = get_client(ctx)
         stack = await client.deck.get_stack(board_id, stack_id)
         return stack.model_dump()
 
@@ -57,7 +71,10 @@ def configure_deck_tools(mcp: FastMCP):
     async def deck_cards_resource(board_id: int, stack_id: int):
         """List all cards in a Nextcloud Deck stack"""
         ctx: Context = mcp.get_context()
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        await ctx.warning(
+            "This resource is deprecated, use the deck_get_cards tool instead"
+        )
+        client = get_client(ctx)
         stack = await client.deck.get_stack(board_id, stack_id)
         if stack.cards:
             return [card.model_dump() for card in stack.cards]
@@ -67,7 +84,10 @@ def configure_deck_tools(mcp: FastMCP):
     async def deck_card_resource(board_id: int, stack_id: int, card_id: int):
         """Get details of a specific Nextcloud Deck card"""
         ctx: Context = mcp.get_context()
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        await ctx.warning(
+            "This resource is deprecated, use the deck_get_card tool instead"
+        )
+        client = get_client(ctx)
         card = await client.deck.get_card(board_id, stack_id, card_id)
         return card.model_dump()
 
@@ -75,7 +95,10 @@ def configure_deck_tools(mcp: FastMCP):
     async def deck_labels_resource(board_id: int):
         """List all labels in a Nextcloud Deck board"""
         ctx: Context = mcp.get_context()
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        await ctx.warning(
+            "This resource is deprecated, use the deck_get_labels tool instead"
+        )
+        client = get_client(ctx)
         board = await client.deck.get_board(board_id)
         return [label.model_dump() for label in board.labels]
 
@@ -83,11 +106,78 @@ def configure_deck_tools(mcp: FastMCP):
     async def deck_label_resource(board_id: int, label_id: int):
         """Get details of a specific Nextcloud Deck label"""
         ctx: Context = mcp.get_context()
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        await ctx.warning(
+            "This resource is deprecated, use the deck_get_label tool instead"
+        )
+        client = get_client(ctx)
         label = await client.deck.get_label(board_id, label_id)
         return label.model_dump()
 
-    # Tools
+    # Read Tools (converted from resources)
+
+    @mcp.tool()
+    async def deck_get_boards(ctx: Context) -> list[DeckBoard]:
+        """Get all Nextcloud Deck boards"""
+        client = get_client(ctx)
+        boards = await client.deck.get_boards()
+        return boards
+
+    @mcp.tool()
+    async def deck_get_board(ctx: Context, board_id: int) -> DeckBoard:
+        """Get details of a specific Nextcloud Deck board"""
+        client = get_client(ctx)
+        board = await client.deck.get_board(board_id)
+        return board
+
+    @mcp.tool()
+    async def deck_get_stacks(ctx: Context, board_id: int) -> list[DeckStack]:
+        """Get all stacks in a Nextcloud Deck board"""
+        client = get_client(ctx)
+        stacks = await client.deck.get_stacks(board_id)
+        return stacks
+
+    @mcp.tool()
+    async def deck_get_stack(ctx: Context, board_id: int, stack_id: int) -> DeckStack:
+        """Get details of a specific Nextcloud Deck stack"""
+        client = get_client(ctx)
+        stack = await client.deck.get_stack(board_id, stack_id)
+        return stack
+
+    @mcp.tool()
+    async def deck_get_cards(
+        ctx: Context, board_id: int, stack_id: int
+    ) -> list[DeckCard]:
+        """Get all cards in a Nextcloud Deck stack"""
+        client = get_client(ctx)
+        stack = await client.deck.get_stack(board_id, stack_id)
+        if stack.cards:
+            return stack.cards
+        return []
+
+    @mcp.tool()
+    async def deck_get_card(
+        ctx: Context, board_id: int, stack_id: int, card_id: int
+    ) -> DeckCard:
+        """Get details of a specific Nextcloud Deck card"""
+        client = get_client(ctx)
+        card = await client.deck.get_card(board_id, stack_id, card_id)
+        return card
+
+    @mcp.tool()
+    async def deck_get_labels(ctx: Context, board_id: int) -> list[DeckLabel]:
+        """Get all labels in a Nextcloud Deck board"""
+        client = get_client(ctx)
+        board = await client.deck.get_board(board_id)
+        return board.labels
+
+    @mcp.tool()
+    async def deck_get_label(ctx: Context, board_id: int, label_id: int) -> DeckLabel:
+        """Get details of a specific Nextcloud Deck label"""
+        client = get_client(ctx)
+        label = await client.deck.get_label(board_id, label_id)
+        return label
+
+    # Create/Update/Delete Tools
 
     @mcp.tool()
     async def deck_create_board(
@@ -99,7 +189,7 @@ def configure_deck_tools(mcp: FastMCP):
             title: The title of the new board
             color: The hexadecimal color of the new board (e.g. FF0000)
         """
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
         board = await client.deck.create_board(title, color)
         return CreateBoardResponse(id=board.id, title=board.title, color=board.color)
 
@@ -116,7 +206,7 @@ def configure_deck_tools(mcp: FastMCP):
             title: The title of the new stack
             order: Order for sorting the stacks
         """
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
         stack = await client.deck.create_stack(board_id, title, order)
         return CreateStackResponse(id=stack.id, title=stack.title, order=stack.order)
 
@@ -136,7 +226,7 @@ def configure_deck_tools(mcp: FastMCP):
             title: New title for the stack
             order: New order for the stack
         """
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
         await client.deck.update_stack(board_id, stack_id, title, order)
         return StackOperationResponse(
             success=True,
@@ -155,7 +245,7 @@ def configure_deck_tools(mcp: FastMCP):
             board_id: The ID of the board
             stack_id: The ID of the stack
         """
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
         await client.deck.delete_stack(board_id, stack_id)
         return StackOperationResponse(
             success=True,
@@ -187,7 +277,7 @@ def configure_deck_tools(mcp: FastMCP):
             description: Description of the card
             duedate: Due date of the card (ISO-8601 format)
         """
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
         card = await client.deck.create_card(
             board_id, stack_id, title, type, order, description, duedate
         )
@@ -228,7 +318,7 @@ def configure_deck_tools(mcp: FastMCP):
             archived: Whether the card should be archived
             done: Completion date for the card (ISO-8601 format)
         """
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
         await client.deck.update_card(
             board_id,
             stack_id,
@@ -261,7 +351,7 @@ def configure_deck_tools(mcp: FastMCP):
             stack_id: The ID of the stack
             card_id: The ID of the card
         """
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
         await client.deck.delete_card(board_id, stack_id, card_id)
         return CardOperationResponse(
             success=True,
@@ -282,7 +372,7 @@ def configure_deck_tools(mcp: FastMCP):
             stack_id: The ID of the stack
             card_id: The ID of the card
         """
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
         await client.deck.archive_card(board_id, stack_id, card_id)
         return CardOperationResponse(
             success=True,
@@ -303,7 +393,7 @@ def configure_deck_tools(mcp: FastMCP):
             stack_id: The ID of the stack
             card_id: The ID of the card
         """
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
         await client.deck.unarchive_card(board_id, stack_id, card_id)
         return CardOperationResponse(
             success=True,
@@ -331,7 +421,7 @@ def configure_deck_tools(mcp: FastMCP):
             order: New position in the target stack
             target_stack_id: The ID of the target stack
         """
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
         await client.deck.reorder_card(
             board_id, stack_id, card_id, order, target_stack_id
         )
@@ -355,7 +445,7 @@ def configure_deck_tools(mcp: FastMCP):
             title: The title of the new label
             color: The color of the new label (hex format without #)
         """
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
         label = await client.deck.create_label(board_id, title, color)
         return CreateLabelResponse(id=label.id, title=label.title, color=label.color)
 
@@ -375,7 +465,7 @@ def configure_deck_tools(mcp: FastMCP):
             title: New title for the label
             color: New color for the label (hex format without #)
         """
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
         await client.deck.update_label(board_id, label_id, title, color)
         return LabelOperationResponse(
             success=True,
@@ -394,7 +484,7 @@ def configure_deck_tools(mcp: FastMCP):
             board_id: The ID of the board
             label_id: The ID of the label
         """
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
         await client.deck.delete_label(board_id, label_id)
         return LabelOperationResponse(
             success=True,
@@ -416,7 +506,7 @@ def configure_deck_tools(mcp: FastMCP):
             card_id: The ID of the card
             label_id: The ID of the label to assign
         """
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
         await client.deck.assign_label_to_card(board_id, stack_id, card_id, label_id)
         return CardOperationResponse(
             success=True,
@@ -438,7 +528,7 @@ def configure_deck_tools(mcp: FastMCP):
             card_id: The ID of the card
             label_id: The ID of the label to remove
         """
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
         await client.deck.remove_label_from_card(board_id, stack_id, card_id, label_id)
         return CardOperationResponse(
             success=True,
@@ -461,7 +551,7 @@ def configure_deck_tools(mcp: FastMCP):
             card_id: The ID of the card
             user_id: The user ID to assign
         """
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
         await client.deck.assign_user_to_card(board_id, stack_id, card_id, user_id)
         return CardOperationResponse(
             success=True,
@@ -483,7 +573,7 @@ def configure_deck_tools(mcp: FastMCP):
             card_id: The ID of the card
             user_id: The user ID to unassign
         """
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
         await client.deck.unassign_user_from_card(board_id, stack_id, card_id, user_id)
         return CardOperationResponse(
             success=True,

nextcloud_mcp_server/server/notes.py

@@ -1,20 +1,20 @@
 import logging
+
 from httpx import HTTPStatusError
+from mcp.server.fastmcp import Context, FastMCP
 from mcp.shared.exceptions import McpError
 from mcp.types import ErrorData
 
-from mcp.server.fastmcp import Context, FastMCP
-
-from nextcloud_mcp_server.client import NextcloudClient
+from nextcloud_mcp_server.context import get_client
 from nextcloud_mcp_server.models.notes import (
-    Note,
-    NotesSettings,
-    CreateNoteResponse,
-    UpdateNoteResponse,
-    DeleteNoteResponse,
     AppendContentResponse,
-    SearchNotesResponse,
+    CreateNoteResponse,
+    DeleteNoteResponse,
+    Note,
     NoteSearchResult,
+    NotesSettings,
+    SearchNotesResponse,
+    UpdateNoteResponse,
 )
 
 logger = logging.getLogger(__name__)
@@ -27,15 +27,15 @@ def configure_notes_tools(mcp: FastMCP):
         ctx: Context = (
             mcp.get_context()
         )  # https://github.com/modelcontextprotocol/python-sdk/issues/244
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
         settings_data = await client.notes.get_settings()
         return NotesSettings(**settings_data)
 
     @mcp.resource("nc://Notes/{note_id}/attachments/{attachment_filename}")
-    async def nc_notes_get_attachment(note_id: int, attachment_filename: str):
+    async def nc_notes_get_attachment_resource(note_id: int, attachment_filename: str):
         """Get a specific attachment from a note"""
         ctx: Context = mcp.get_context()
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
         # Assuming a method get_note_attachment exists in the client
         # This method should return the raw content and determine the mime type
         content, mime_type = await client.webdav.get_note_attachment(
@@ -53,11 +53,11 @@ def configure_notes_tools(mcp: FastMCP):
         }
 
     @mcp.resource("nc://Notes/{note_id}")
-    async def nc_get_note(note_id: int):
+    async def nc_get_note_resource(note_id: int):
         """Get user note using note id"""
 
         ctx: Context = mcp.get_context()
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
         try:
             note_data = await client.notes.get_note(note_id)
             return Note(**note_data)
@@ -81,7 +81,7 @@ def configure_notes_tools(mcp: FastMCP):
         title: str, content: str, category: str, ctx: Context
     ) -> CreateNoteResponse:
         """Create a new note"""
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
         try:
             note_data = await client.notes.create_note(
                 title=title,
@@ -129,11 +129,11 @@ def configure_notes_tools(mcp: FastMCP):
         """Update an existing note's title, content, or category.
 
         REQUIRED: etag parameter must be provided to prevent overwriting concurrent changes.
-        Get the current ETag by first retrieving the note using nc://Notes/{note_id} resource.
+        Get the current ETag by first retrieving the note using nc_notes_get_note tool.
         If the note has been modified by someone else since you retrieved it,
         the update will fail with a 412 error."""
         logger.info("Updating note %s", note_id)
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
         try:
             note_data = await client.notes.update(
                 note_id=note_id,
@@ -183,7 +183,7 @@ def configure_notes_tools(mcp: FastMCP):
         between the note and what will be appended."""
 
         logger.info("Appending content to note %s", note_id)
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
         try:
             note_data = await client.notes.append_content(
                 note_id=note_id, content=content
@@ -220,7 +220,7 @@ def configure_notes_tools(mcp: FastMCP):
     @mcp.tool()
     async def nc_notes_search_notes(query: str, ctx: Context) -> SearchNotesResponse:
         """Search notes by title or content, returning only id, title, and category."""
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
         try:
             search_results_raw = await client.notes_search_notes(query=query)
 
@@ -258,11 +258,71 @@ def configure_notes_tools(mcp: FastMCP):
                     )
                 )
 
+    @mcp.tool()
+    async def nc_notes_get_note(note_id: int, ctx: Context) -> Note:
+        """Get a specific note by its ID"""
+        client = get_client(ctx)
+        try:
+            note_data = await client.notes.get_note(note_id)
+            return Note(**note_data)
+        except HTTPStatusError as e:
+            if e.response.status_code == 404:
+                raise McpError(ErrorData(code=-1, message=f"Note {note_id} not found"))
+            elif e.response.status_code == 403:
+                raise McpError(
+                    ErrorData(code=-1, message=f"Access denied to note {note_id}")
+                )
+            else:
+                raise McpError(
+                    ErrorData(
+                        code=-1,
+                        message=f"Failed to retrieve note {note_id}: {e.response.reason_phrase}",
+                    )
+                )
+
+    @mcp.tool()
+    async def nc_notes_get_attachment(
+        note_id: int, attachment_filename: str, ctx: Context
+    ) -> dict[str, str]:
+        """Get a specific attachment from a note"""
+        client = get_client(ctx)
+        try:
+            content, mime_type = await client.webdav.get_note_attachment(
+                note_id=note_id, filename=attachment_filename
+            )
+            return {
+                "uri": f"nc://Notes/{note_id}/attachments/{attachment_filename}",
+                "mimeType": mime_type,
+                "data": content,
+            }
+        except HTTPStatusError as e:
+            if e.response.status_code == 404:
+                raise McpError(
+                    ErrorData(
+                        code=-1,
+                        message=f"Attachment {attachment_filename} not found for note {note_id}",
+                    )
+                )
+            elif e.response.status_code == 403:
+                raise McpError(
+                    ErrorData(
+                        code=-1,
+                        message=f"Access denied to attachment {attachment_filename} for note {note_id}",
+                    )
+                )
+            else:
+                raise McpError(
+                    ErrorData(
+                        code=-1,
+                        message=f"Failed to retrieve attachment: {e.response.reason_phrase}",
+                    )
+                )
+
     @mcp.tool()
     async def nc_notes_delete_note(note_id: int, ctx: Context) -> DeleteNoteResponse:
         """Delete a note permanently"""
         logger.info("Deleting note %s", note_id)
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
         try:
             await client.notes.delete_note(note_id)
             return DeleteNoteResponse(

nextcloud_mcp_server/server/sharing.py

@@ -0,0 +1,133 @@
+"""MCP tools for Nextcloud file/folder sharing operations."""
+
+import json
+
+from nextcloud_mcp_server.context import get_client
+from mcp.server.fastmcp import Context, FastMCP
+
+
+def configure_sharing_tools(mcp: FastMCP):
+    """Configure sharing-related MCP tools.
+
+    Args:
+        mcp: FastMCP server instance
+    """
+
+    @mcp.tool()
+    async def nc_share_create(
+        path: str,
+        share_with: str,
+        ctx: Context,
+        share_type: int = 0,
+        permissions: int = 1,
+    ) -> str:
+        """Create a share for a file or folder in Nextcloud.
+
+        Share a file or folder with another user or group. The authenticated user
+        must own the file/folder being shared.
+
+        Args:
+            path: Path to file/folder to share (relative to your files, e.g., "/document.txt")
+            share_with: Username (for user share) or group name (for group share)
+            share_type: Share type - 0 for user (default), 1 for group, 3 for public link
+            permissions: Share permissions (default: 1 for read-only):
+                - 1 = read
+                - 2 = update
+                - 4 = create
+                - 8 = delete
+                - 16 = share
+                - 31 = all permissions
+                Common: 1 (read-only), 3 (read+update), 15 (read+update+create+delete)
+
+        Returns:
+            JSON string with share information including share ID
+        """
+        client = get_client(ctx)
+        share_data = await client.sharing.create_share(
+            path=path,
+            share_with=share_with,
+            share_type=share_type,
+            permissions=permissions,
+        )
+        return json.dumps(share_data, indent=2)
+
+    @mcp.tool()
+    async def nc_share_delete(share_id: int, ctx: Context) -> str:
+        """Delete a share by its ID.
+
+        Remove a share that you created. You must be the owner of the share.
+
+        Args:
+            share_id: The ID of the share to delete
+
+        Returns:
+            JSON string confirming deletion
+        """
+        client = get_client(ctx)
+        await client.sharing.delete_share(share_id)
+        return json.dumps(
+            {"success": True, "message": f"Share {share_id} deleted"}, indent=2
+        )
+
+    @mcp.tool()
+    async def nc_share_get(share_id: int, ctx: Context) -> str:
+        """Get information about a specific share.
+
+        Retrieve details about a share by its ID. You must have access to the share
+        (either as owner or recipient).
+
+        Args:
+            share_id: The ID of the share
+
+        Returns:
+            JSON string with share information
+        """
+        client = get_client(ctx)
+        share_data = await client.sharing.get_share(share_id)
+        return json.dumps(share_data, indent=2)
+
+    @mcp.tool()
+    async def nc_share_list(
+        ctx: Context, path: str | None = None, shared_with_me: bool = False
+    ) -> str:
+        """List shares created by you or shared with you.
+
+        Args:
+            path: Optional path to filter shares for a specific file/folder
+            shared_with_me: If True, list shares that others shared with you.
+                          If False (default), list shares you created.
+
+        Returns:
+            JSON string with list of shares
+        """
+        client = get_client(ctx)
+        shares = await client.sharing.list_shares(
+            path=path, shared_with_me=shared_with_me
+        )
+        return json.dumps(shares, indent=2)
+
+    @mcp.tool()
+    async def nc_share_update(share_id: int, permissions: int, ctx: Context) -> str:
+        """Update the permissions of an existing share.
+
+        Modify the permissions for a share you created. You must be the owner.
+
+        Args:
+            share_id: The ID of the share to update
+            permissions: New permissions value:
+                - 1 = read
+                - 2 = update
+                - 4 = create
+                - 8 = delete
+                - 16 = share
+                - 31 = all permissions
+                Common: 1 (read-only), 3 (read+update), 15 (read+update+create+delete)
+
+        Returns:
+            JSON string with updated share information
+        """
+        client = get_client(ctx)
+        share_data = await client.sharing.update_share(
+            share_id=share_id, permissions=permissions
+        )
+        return json.dumps(share_data, indent=2)

nextcloud_mcp_server/server/tables.py

@@ -2,7 +2,7 @@ import logging
 
 from mcp.server.fastmcp import Context, FastMCP
 
-from nextcloud_mcp_server.client import NextcloudClient
+from nextcloud_mcp_server.context import get_client
 
 logger = logging.getLogger(__name__)
 
@@ -12,13 +12,13 @@ def configure_tables_tools(mcp: FastMCP):
     @mcp.tool()
     async def nc_tables_list_tables(ctx: Context):
         """List all tables available to the user"""
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
         return await client.tables.list_tables()
 
     @mcp.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: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
         return await client.tables.get_table_schema(table_id)
 
     @mcp.tool()
@@ -29,7 +29,7 @@ def configure_tables_tools(mcp: FastMCP):
         offset: int | None = None,
     ):
         """Read rows from a table with optional pagination"""
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
         return await client.tables.get_table_rows(table_id, limit, offset)
 
     @mcp.tool()
@@ -38,7 +38,7 @@ def configure_tables_tools(mcp: FastMCP):
 
         Data should be a dictionary mapping column IDs to values, e.g. {1: "text", 2: 42}
         """
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
         return await client.tables.create_row(table_id, data)
 
     @mcp.tool()
@@ -47,11 +47,11 @@ def configure_tables_tools(mcp: FastMCP):
 
         Data should be a dictionary mapping column IDs to new values, e.g. {1: "new text", 2: 99}
         """
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
         return await client.tables.update_row(row_id, data)
 
     @mcp.tool()
     async def nc_tables_delete_row(row_id: int, ctx: Context):
         """Delete a row from a table"""
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
         return await client.tables.delete_row(row_id)

nextcloud_mcp_server/server/webdav.py

@@ -2,7 +2,7 @@ import logging
 
 from mcp.server.fastmcp import Context, FastMCP
 
-from nextcloud_mcp_server.client import NextcloudClient
+from nextcloud_mcp_server.context import get_client
 
 logger = logging.getLogger(__name__)
 
@@ -26,7 +26,7 @@ def configure_webdav_tools(mcp: FastMCP):
             # List a specific folder
             await nc_webdav_list_directory("Documents/Projects")
         """
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
         return await client.webdav.list_directory(path)
 
     @mcp.tool()
@@ -49,7 +49,7 @@ def configure_webdav_tools(mcp: FastMCP):
             result = await nc_webdav_read_file("Images/photo.jpg")
             logger.info(result['encoding'])  # 'base64'
         """
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
         content, content_type = await client.webdav.read_file(path)
 
         # For text files, decode content for easier viewing
@@ -97,7 +97,7 @@ def configure_webdav_tools(mcp: FastMCP):
             # Write binary data (base64 encoded)
             await nc_webdav_write_file("files/data.bin", base64_content, "application/octet-stream;base64")
         """
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
 
         # Handle base64 encoded content
         if content_type and "base64" in content_type.lower():
@@ -127,7 +127,7 @@ def configure_webdav_tools(mcp: FastMCP):
             # Create nested directories (parent must exist)
             await nc_webdav_create_directory("Projects/MyApp/docs")
         """
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
         return await client.webdav.create_directory(path)
 
     @mcp.tool()
@@ -147,7 +147,7 @@ def configure_webdav_tools(mcp: FastMCP):
             # Delete a directory (will delete all contents)
             await nc_webdav_delete_resource("temp_folder")
         """
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
         return await client.webdav.delete_resource(path)
 
     @mcp.tool()
@@ -177,7 +177,7 @@ def configure_webdav_tools(mcp: FastMCP):
             # Move and overwrite if destination exists
             await nc_webdav_move_resource("document.txt", "Archive/document.txt", overwrite=True)
         """
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
         return await client.webdav.move_resource(
             source_path, destination_path, overwrite
         )
@@ -209,7 +209,7 @@ def configure_webdav_tools(mcp: FastMCP):
             # Copy and overwrite if destination exists
             await nc_webdav_copy_resource("document.txt", "Backup/document.txt", overwrite=True)
         """
-        client: NextcloudClient = ctx.request_context.lifespan_context.client
+        client = get_client(ctx)
         return await client.webdav.copy_resource(
             source_path, destination_path, overwrite
         )

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "nextcloud-mcp-server"
-version = "0.12.1"
+version = "0.13.0"
 description = ""
 authors = [
     {name = "Chris Coutinho",email = "chris@coutinho.io"}
@@ -8,7 +8,7 @@ authors = [
 readme = "README.md"
 requires-python = ">=3.11"
 dependencies = [
-    "mcp[cli] (>=1.13,<1.14)",
+    "mcp[cli] (>=1.17,<1.18)",
     "httpx (>=0.28.1,<0.29.0)",
     "pillow (>=11.2.1,<12.0.0)",
     "icalendar (>=6.0.0,<7.0.0)",
@@ -25,7 +25,11 @@ log_cli = 1
 log_cli_level = "INFO"
 log_level = "INFO"
 markers = [
-    "integration: marks tests as slow (deselect with '-m \"not slow\"')"
+    "integration: marks tests as slow (deselect with '-m \"not slow\"')",
+    "oauth: marks tests as oauth (deselect with '-m \"not oauth\"')"
+]
+testpaths = [
+    "tests",
 ]
 
 [tool.commitizen]
@@ -44,9 +48,11 @@ build-backend = "poetry.core.masonry.api"
 dev = [
     "commitizen>=4.8.2",
     "ipython>=9.2.0",
+    "playwright>=1.49.1",
     "pytest>=8.3.5",
     "pytest-asyncio>=1.0.0",
     "pytest-cov>=6.1.1",
+    "pytest-playwright-asyncio>=0.7.1",
     "ruff>=0.11.13",
 ]
 

tests/client/calendar/test_field_preservation.py

@@ -5,10 +5,11 @@ are present in calendar events and contacts during round-trip operations.
 """
 
 import logging
-import pytest
 import uuid
 from datetime import datetime, timedelta
 
+import pytest
+
 logger = logging.getLogger(__name__)
 
 

tests/client/deck/test_deck_api.py

@@ -5,7 +5,7 @@ import pytest
 from httpx import HTTPStatusError
 
 from nextcloud_mcp_server.client import NextcloudClient
-from nextcloud_mcp_server.models.deck import DeckStack, DeckCard, DeckLabel
+from nextcloud_mcp_server.models.deck import DeckCard, DeckLabel, DeckStack
 
 logger = logging.getLogger(__name__)
 pytestmark = pytest.mark.integration

tests/client/test_oauth.py

@@ -0,0 +1,103 @@
+"""Integration tests for OAuth authentication."""
+
+import logging
+import os
+
+import pytest
+from httpx import HTTPStatusError
+
+from nextcloud_mcp_server.auth import BearerAuth
+from nextcloud_mcp_server.client import NextcloudClient
+
+logger = logging.getLogger(__name__)
+
+pytestmark = [pytest.mark.integration, pytest.mark.oauth]
+
+
+# OAuth Client Tests
+
+
+async def test_oauth_client_capabilities(nc_oauth_client: NextcloudClient):
+    """Test that OAuth client can fetch capabilities."""
+    capabilities = await nc_oauth_client.capabilities()
+
+    assert capabilities is not None
+    assert "ocs" in capabilities
+    logger.info(
+        f"OAuth client successfully fetched capabilities: {capabilities.get('ocs').get('meta')}"
+    )
+
+
+async def test_oauth_client_notes_list(nc_oauth_client: NextcloudClient):
+    """Test that OAuth client can list notes."""
+    notes = await nc_oauth_client.notes.get_all_notes()
+
+    assert isinstance(notes, list)
+    logger.info(f"OAuth client successfully listed {len(notes)} notes")
+
+
+async def test_oauth_client_create_note(nc_oauth_client: NextcloudClient):
+    """Test that OAuth client can create and delete a note."""
+    # Create note
+    note_title = "OAuth Test Note"
+    note_content = "This note was created with OAuth authentication"
+
+    created_note = await nc_oauth_client.notes.create_note(
+        title=note_title, content=note_content
+    )
+
+    assert created_note is not None
+    assert created_note.get("title") == note_title
+    note_id = created_note.get("id")
+    assert note_id is not None
+
+    logger.info(f"OAuth client successfully created note with ID: {note_id}")
+
+    # Clean up - delete the note
+    try:
+        await nc_oauth_client.notes.delete_note(note_id=note_id)
+        logger.info(f"OAuth client successfully deleted note {note_id}")
+    except Exception as e:
+        logger.error(f"Failed to clean up test note {note_id}: {e}")
+        raise
+
+
+# OAuth Token Validation Tests
+
+
+async def test_token_in_request_headers(
+    nc_oauth_client: NextcloudClient, playwright_oauth_token: str
+):
+    """Verify that bearer token is being used in requests."""
+    # The client should be using BearerAuth
+    assert nc_oauth_client._client.auth is not None
+
+    # Make a request and verify it works
+    capabilities = await nc_oauth_client.capabilities()
+    assert capabilities is not None
+
+    logger.info("OAuth bearer token is correctly included in requests")
+
+
+async def test_invalid_token_fails():
+    """Test that an invalid token results in authentication failure."""
+    nextcloud_host = os.getenv("NEXTCLOUD_HOST")
+    if not nextcloud_host:
+        pytest.skip("NEXTCLOUD_HOST not set")
+
+    # Create client with invalid token using BearerAuth
+    invalid_client = NextcloudClient(
+        base_url=nextcloud_host,
+        username="testuser",
+        auth=BearerAuth("invalid_token_12345"),
+    )
+
+    # Attempt to use a protected endpoint - should fail with 401
+    # Note: capabilities endpoint is public and doesn't require auth
+    with pytest.raises(HTTPStatusError) as exc_info:
+        await invalid_client.notes.get_all_notes()
+
+    assert exc_info.value.response.status_code == 401
+
+    await invalid_client.close()
+    logger.info("Invalid OAuth token correctly rejected")

tests/client/test_oauth_interactive.py

@@ -0,0 +1,41 @@
+"""Interactive integration tests for OAuth authentication."""
+
+import logging
+import os
+
+import pytest
+
+logger = logging.getLogger(__name__)
+
+pytestmark = [pytest.mark.integration, pytest.mark.oauth]
+
+
+@pytest.mark.skipif(
+    "GITHUB_ACTIONS" in os.environ,
+    reason="Unable to access interactive browser in GitHub Actions",
+)
+async def test_oauth_client_with_interactive_flow(nc_oauth_client_interactive):
+    """Test that OAuth client created via interactive flow can access Nextcloud APIs."""
+    # Test 1: Check capabilities
+    capabilities = await nc_oauth_client_interactive.capabilities()
+    assert capabilities is not None
+    logger.info("OAuth client (interactive) successfully fetched capabilities")
+
+    # Test 2: List notes
+    notes = await nc_oauth_client_interactive.notes.get_all_notes()
+    assert isinstance(notes, list)
+    logger.info(f"OAuth client (interactive) successfully listed {len(notes)} notes")
+
+    # Test 3: Create and delete a note
+    test_note = await nc_oauth_client_interactive.notes.create_note(
+        title="OAuth Interactive Test Note",
+        content="This note was created during OAuth interactive testing",
+    )
+    assert test_note is not None
+    assert test_note.get("id") is not None
+    note_id = test_note["id"]
+    logger.info(f"OAuth client (interactive) successfully created note {note_id}")
+
+    # Clean up
+    await nc_oauth_client_interactive.notes.delete_note(note_id=note_id)
+    logger.info(f"OAuth client (interactive) successfully deleted note {note_id}")

tests/client/test_oauth_playwright.py

@@ -0,0 +1,32 @@
+"""Integration tests for Playwright-based OAuth authentication."""
+
+import logging
+
+import pytest
+
+logger = logging.getLogger(__name__)
+
+pytestmark = [pytest.mark.integration, pytest.mark.oauth]
+
+
+async def test_playwright_oauth_token_acquisition(playwright_oauth_token: str):
+    """Test that Playwright can acquire an OAuth token automatically."""
+    assert playwright_oauth_token is not None
+    assert isinstance(playwright_oauth_token, str)
+    assert len(playwright_oauth_token) > 0
+    logger.info(
+        f"Successfully acquired OAuth token via Playwright: {playwright_oauth_token[:20]}..."
+    )
+
+
+async def test_oauth_client_with_playwright_flow(nc_oauth_client_playwright):
+    """Test that OAuth client created via Playwright flow can access Nextcloud APIs."""
+    # Test 1: Check capabilities
+    capabilities = await nc_oauth_client_playwright.capabilities()
+    assert capabilities is not None
+    logger.info("OAuth client (Playwright) successfully fetched capabilities")
+
+    # Test 2: List notes
+    notes = await nc_oauth_client_playwright.notes.get_all_notes()
+    assert isinstance(notes, list)
+    logger.info(f"OAuth client (Playwright) successfully listed {len(notes)} notes")

tests/client/test_sharing_api.py

@@ -0,0 +1,172 @@
+"""Integration tests for Nextcloud Sharing API client."""
+
+import logging
+
+import pytest
+
+logger = logging.getLogger(__name__)
+
+pytestmark = pytest.mark.integration
+
+
+@pytest.mark.asyncio
+async def test_create_and_delete_share(nc_client):
+    """Test creating and deleting a file share."""
+    # Create a test user to share with
+    test_user = "testuser3"
+    try:
+        await nc_client.users.create_user(
+            userid=test_user, password="SecureP@ssw0rd!2024TestUser"
+        )
+    except Exception:
+        pass  # User might already exist
+
+    # Create a test file
+    file_path = "/test_share_file.txt"
+    file_content = b"Test file for sharing"
+
+    await nc_client.webdav.write_file(file_path, file_content)
+
+    share_id = None
+    try:
+        # Create a share
+        share_data = await nc_client.sharing.create_share(
+            path=file_path,
+            share_with=test_user,  # Share with test user
+            share_type=0,  # User share
+            permissions=1,  # Read-only
+        )
+
+        assert share_data is not None
+        assert "id" in share_data
+        share_id = share_data["id"]
+        logger.info(f"Created share: {share_id}")
+
+        # Get share info
+        share_info = await nc_client.sharing.get_share(share_id)
+        assert share_info["id"] == share_id
+        assert share_info["path"] == file_path
+        assert share_info["permissions"] == 1
+
+        # List shares
+        shares = await nc_client.sharing.list_shares(path=file_path)
+        assert len(shares) > 0
+        assert any(s["id"] == share_id for s in shares)
+
+    finally:
+        # Cleanup
+        if share_id:
+            await nc_client.sharing.delete_share(share_id)
+            logger.info(f"Deleted share: {share_id}")
+
+        await nc_client.webdav.delete_resource(file_path)
+
+        # Cleanup test user
+        try:
+            await nc_client.users.delete_user(test_user)
+        except Exception:
+            pass
+
+
+@pytest.mark.asyncio
+async def test_update_share_permissions(nc_client):
+    """Test updating share permissions."""
+    # Create a test user to share with
+    test_user = "testuser3"
+    try:
+        await nc_client.users.create_user(
+            userid=test_user, password="SecureP@ssw0rd!2024TestUser"
+        )
+    except Exception:
+        pass  # User might already exist
+
+    # Create a test file
+    file_path = "/test_share_update.txt"
+    file_content = b"Test file for permission updates"
+
+    await nc_client.webdav.write_file(file_path, file_content)
+
+    share_id = None
+    try:
+        # Create a share with read-only permissions
+        share_data = await nc_client.sharing.create_share(
+            path=file_path,
+            share_with=test_user,
+            share_type=0,
+            permissions=1,  # Read-only
+        )
+        share_id = share_data["id"]
+
+        # Update to read+write permissions
+        updated_share = await nc_client.sharing.update_share(
+            share_id=share_id,
+            permissions=3,  # Read + Write
+        )
+
+        assert updated_share["id"] == share_id
+        assert updated_share["permissions"] == 3
+
+    finally:
+        # Cleanup
+        if share_id:
+            await nc_client.sharing.delete_share(share_id)
+
+        await nc_client.webdav.delete_resource(file_path)
+
+        # Cleanup test user
+        try:
+            await nc_client.users.delete_user(test_user)
+        except Exception:
+            pass
+
+
+@pytest.mark.asyncio
+async def test_list_shares(nc_client):
+    """Test listing all shares."""
+    # Create a test user to share with
+    test_user = "testuser3"
+    try:
+        await nc_client.users.create_user(
+            userid=test_user, password="SecureP@ssw0rd!2024TestUser"
+        )
+    except Exception:
+        pass  # User might already exist
+
+    # Create a test file
+    file_path = "/test_list_shares.txt"
+    file_content = b"Test file for listing shares"
+
+    await nc_client.webdav.write_file(file_path, file_content)
+
+    share_id = None
+    try:
+        # Create a share
+        share_data = await nc_client.sharing.create_share(
+            path=file_path,
+            share_with=test_user,
+            share_type=0,
+            permissions=1,
+        )
+        share_id = share_data["id"]
+
+        # List all shares
+        all_shares = await nc_client.sharing.list_shares()
+        assert len(all_shares) > 0
+
+        # List shares for specific file
+        file_shares = await nc_client.sharing.list_shares(path=file_path)
+        assert len(file_shares) > 0
+        assert any(s["id"] == share_id for s in file_shares)
+
+    finally:
+        # Cleanup
+        if share_id:
+            await nc_client.sharing.delete_share(share_id)
+
+        await nc_client.webdav.delete_resource(file_path)
+
+        # Cleanup test user
+        try:
+            await nc_client.users.delete_user(test_user)
+        except Exception:
+            pass

tests/server/test_deck_advanced_features.py

@@ -0,0 +1,569 @@
+import json
+import logging
+import uuid
+
+import pytest
+from mcp import ClientSession
+
+from nextcloud_mcp_server.client import NextcloudClient
+
+logger = logging.getLogger(__name__)
+pytestmark = pytest.mark.integration
+
+
+# Stack MCP Tools Tests
+async def test_deck_stack_mcp_tools(
+    nc_mcp_client: ClientSession, nc_client: NextcloudClient, temporary_board: dict
+):
+    """Test complete deck stack operations via MCP tools."""
+    board_id = temporary_board["id"]
+    stack_title = f"MCP Test Stack {uuid.uuid4().hex[:8]}"
+    stack_order = 1
+
+    # 1. Create stack via MCP tool
+    logger.info(f"Creating stack via MCP: {stack_title}")
+    create_result = await nc_mcp_client.call_tool(
+        "deck_create_stack",
+        {"board_id": board_id, "title": stack_title, "order": stack_order},
+    )
+
+    assert create_result.isError is False, (
+        f"MCP stack creation failed: {create_result.content}"
+    )
+    created_stack_response = json.loads(create_result.content[0].text)
+    stack_id = created_stack_response["id"]
+    assert created_stack_response["title"] == stack_title
+    assert created_stack_response["order"] == stack_order
+    logger.info(f"Stack created via MCP with ID: {stack_id}")
+
+    try:
+        # 2. Get stack via MCP resource
+        logger.info(f"Getting stack via MCP resource: {stack_id}")
+        get_result = await nc_mcp_client.read_resource(
+            f"nc://Deck/boards/{board_id}/stacks/{stack_id}"
+        )
+
+        assert len(get_result.contents) == 1, "Expected exactly one content item"
+        get_stack_response = json.loads(get_result.contents[0].text)
+        assert get_stack_response["title"] == stack_title
+        logger.info("Stack retrieved via MCP resource successfully")
+
+        # 3. Update stack via MCP tool
+        updated_title = f"Updated {stack_title}"
+        updated_order = 2
+        logger.info(f"Updating stack via MCP tool: {stack_id}")
+        update_result = await nc_mcp_client.call_tool(
+            "deck_update_stack",
+            {
+                "board_id": board_id,
+                "stack_id": stack_id,
+                "title": updated_title,
+                "order": updated_order,
+            },
+        )
+
+        assert update_result.isError is False, (
+            f"MCP stack update failed: {update_result.content}"
+        )
+        logger.info("Stack updated via MCP tool successfully")
+
+        # 4. Verify update via direct client
+        updated_stack = await nc_client.deck.get_stack(board_id, stack_id)
+        assert updated_stack.title == updated_title
+        assert updated_stack.order == updated_order
+        logger.info("Stack update verified via direct client")
+
+        # 5. List stacks via MCP resource
+        logger.info("Listing stacks via MCP resource")
+        list_result = await nc_mcp_client.read_resource(
+            f"nc://Deck/boards/{board_id}/stacks"
+        )
+
+        assert len(list_result.contents) == 1, "Expected exactly one content item"
+        stacks_data = json.loads(list_result.contents[0].text)
+        assert isinstance(stacks_data, list)
+
+        # Verify our stack is in the list
+        stack_ids = [stack["id"] for stack in stacks_data]
+        assert stack_id in stack_ids, "Updated stack not found in list"
+        logger.info(f"Stack {stack_id} found in stacks list")
+
+        # 6. Read stack via MCP resource
+        logger.info(f"Reading stack via MCP resource: {stack_id}")
+        read_result = await nc_mcp_client.read_resource(
+            f"nc://Deck/boards/{board_id}/stacks/{stack_id}"
+        )
+        read_stack_data = json.loads(read_result.contents[0].text)
+        assert read_stack_data["title"] == updated_title
+        logger.info("Stack read via MCP resource successfully")
+
+    finally:
+        # Clean up
+        await nc_client.deck.delete_stack(board_id, stack_id)
+        logger.info(f"Cleaned up stack ID: {stack_id}")
+
+
+# Card MCP Tools Tests
+async def test_deck_card_mcp_tools(
+    nc_mcp_client: ClientSession,
+    nc_client: NextcloudClient,
+    temporary_board_with_stack: tuple,
+):
+    """Test complete deck card operations via MCP tools."""
+    board_data, stack_data = temporary_board_with_stack
+    board_id = board_data["id"]
+    stack_id = stack_data["id"]
+    card_title = f"MCP Test Card {uuid.uuid4().hex[:8]}"
+    card_description = f"Test description for {card_title}"
+
+    # 1. Create card via MCP tool
+    logger.info(f"Creating card via MCP: {card_title}")
+    create_result = await nc_mcp_client.call_tool(
+        "deck_create_card",
+        {
+            "board_id": board_id,
+            "stack_id": stack_id,
+            "title": card_title,
+            "description": card_description,
+            "type": "plain",
+            "order": 1,
+        },
+    )
+
+    assert create_result.isError is False, (
+        f"MCP card creation failed: {create_result.content}"
+    )
+    created_card_response = json.loads(create_result.content[0].text)
+    card_id = created_card_response["id"]
+    assert created_card_response["title"] == card_title
+    assert created_card_response["description"] == card_description
+    logger.info(f"Card created via MCP with ID: {card_id}")
+
+    try:
+        # 2. Get card via MCP resource
+        logger.info(f"Getting card via MCP resource: {card_id}")
+        get_result = await nc_mcp_client.read_resource(
+            f"nc://Deck/boards/{board_id}/stacks/{stack_id}/cards/{card_id}"
+        )
+
+        assert len(get_result.contents) == 1, "Expected exactly one content item"
+        get_card_response = json.loads(get_result.contents[0].text)
+        assert get_card_response["title"] == card_title
+        logger.info("Card retrieved via MCP resource successfully")
+
+        # 3. Update card via MCP tool
+        updated_title = f"Updated {card_title}"
+        updated_description = f"Updated description for {card_title}"
+        logger.info(f"Updating card via MCP tool: {card_id}")
+        update_result = await nc_mcp_client.call_tool(
+            "deck_update_card",
+            {
+                "board_id": board_id,
+                "stack_id": stack_id,
+                "card_id": card_id,
+                "title": updated_title,
+                "description": updated_description,
+            },
+        )
+
+        assert update_result.isError is False, (
+            f"MCP card update failed: {update_result.content}"
+        )
+        logger.info("Card updated via MCP tool successfully")
+
+        # 4. Verify update via direct client
+        updated_card = await nc_client.deck.get_card(board_id, stack_id, card_id)
+        assert updated_card.title == updated_title
+        assert updated_card.description == updated_description
+        logger.info("Card update verified via direct client")
+
+        # 5. Archive/unarchive card via MCP tools
+        logger.info(f"Archiving card via MCP tool: {card_id}")
+        archive_result = await nc_mcp_client.call_tool(
+            "deck_archive_card",
+            {"board_id": board_id, "stack_id": stack_id, "card_id": card_id},
+        )
+
+        assert archive_result.isError is False, (
+            f"MCP card archive failed: {archive_result.content}"
+        )
+        logger.info("Card archived via MCP tool successfully")
+
+        logger.info(f"Unarchiving card via MCP tool: {card_id}")
+        unarchive_result = await nc_mcp_client.call_tool(
+            "deck_unarchive_card",
+            {"board_id": board_id, "stack_id": stack_id, "card_id": card_id},
+        )
+
+        assert unarchive_result.isError is False, (
+            f"MCP card unarchive failed: {unarchive_result.content}"
+        )
+        logger.info("Card unarchived via MCP tool successfully")
+
+        # 6. Move card to different position via MCP tool
+        logger.info(f"Reordering card via MCP tool: {card_id}")
+        reorder_result = await nc_mcp_client.call_tool(
+            "deck_reorder_card",
+            {
+                "board_id": board_id,
+                "stack_id": stack_id,
+                "card_id": card_id,
+                "order": 10,
+                "target_stack_id": stack_id,
+            },
+        )
+
+        assert reorder_result.isError is False, (
+            f"MCP card reorder failed: {reorder_result.content}"
+        )
+        logger.info("Card reordered via MCP tool successfully")
+
+        # 7. Read card via MCP resource
+        logger.info(f"Reading card via MCP resource: {card_id}")
+        read_result = await nc_mcp_client.read_resource(
+            f"nc://Deck/boards/{board_id}/stacks/{stack_id}/cards/{card_id}"
+        )
+        read_card_data = json.loads(read_result.contents[0].text)
+        assert read_card_data["title"] == updated_title
+        logger.info("Card read via MCP resource successfully")
+
+    finally:
+        # Clean up
+        await nc_client.deck.delete_card(board_id, stack_id, card_id)
+        logger.info(f"Cleaned up card ID: {card_id}")
+
+
+# Label MCP Tools Tests
+async def test_deck_label_mcp_tools(
+    nc_mcp_client: ClientSession, nc_client: NextcloudClient, temporary_board: dict
+):
+    """Test complete deck label operations via MCP tools."""
+    board_id = temporary_board["id"]
+    label_title = f"MCP Test Label {uuid.uuid4().hex[:8]}"
+    label_color = "FF0000"  # Red
+
+    # 1. Create label via MCP tool
+    logger.info(f"Creating label via MCP: {label_title}")
+    create_result = await nc_mcp_client.call_tool(
+        "deck_create_label",
+        {"board_id": board_id, "title": label_title, "color": label_color},
+    )
+
+    assert create_result.isError is False, (
+        f"MCP label creation failed: {create_result.content}"
+    )
+    created_label_response = json.loads(create_result.content[0].text)
+    label_id = created_label_response["id"]
+    assert created_label_response["title"] == label_title
+    assert created_label_response["color"] == label_color
+    logger.info(f"Label created via MCP with ID: {label_id}")
+
+    try:
+        # 2. Get label via MCP resource
+        logger.info(f"Getting label via MCP resource: {label_id}")
+        get_result = await nc_mcp_client.read_resource(
+            f"nc://Deck/boards/{board_id}/labels/{label_id}"
+        )
+
+        assert len(get_result.contents) == 1, "Expected exactly one content item"
+        get_label_response = json.loads(get_result.contents[0].text)
+        assert get_label_response["title"] == label_title
+        logger.info("Label retrieved via MCP resource successfully")
+
+        # 3. Update label via MCP tool
+        updated_title = f"Updated {label_title}"
+        updated_color = "00FF00"  # Green
+        logger.info(f"Updating label via MCP tool: {label_id}")
+        update_result = await nc_mcp_client.call_tool(
+            "deck_update_label",
+            {
+                "board_id": board_id,
+                "label_id": label_id,
+                "title": updated_title,
+                "color": updated_color,
+            },
+        )
+
+        assert update_result.isError is False, (
+            f"MCP label update failed: {update_result.content}"
+        )
+        logger.info("Label updated via MCP tool successfully")
+
+        # 4. Verify update via direct client
+        updated_label = await nc_client.deck.get_label(board_id, label_id)
+        assert updated_label.title == updated_title
+        assert updated_label.color == updated_color
+        logger.info("Label update verified via direct client")
+
+        # 5. Read label via MCP resource
+        logger.info(f"Reading label via MCP resource: {label_id}")
+        read_result = await nc_mcp_client.read_resource(
+            f"nc://Deck/boards/{board_id}/labels/{label_id}"
+        )
+        read_label_data = json.loads(read_result.contents[0].text)
+        assert read_label_data["title"] == updated_title
+        logger.info("Label read via MCP resource successfully")
+
+    finally:
+        # Clean up
+        await nc_client.deck.delete_label(board_id, label_id)
+        logger.info(f"Cleaned up label ID: {label_id}")
+
+
+# Label-Card Assignment Tests
+async def test_deck_card_label_assignment_mcp_tools(
+    nc_mcp_client: ClientSession,
+    nc_client: NextcloudClient,
+    temporary_board_with_card: tuple,
+):
+    """Test card-label assignment operations via MCP tools."""
+    board_data, stack_data, card_data = temporary_board_with_card
+    board_id = board_data["id"]
+    stack_id = stack_data["id"]
+    card_id = card_data["id"]
+
+    # Create a label for assignment
+    label = await nc_client.deck.create_label(
+        board_id, "Assignment Test Label", "0000FF"
+    )
+    label_id = label.id
+
+    try:
+        # 1. Assign label to card via MCP tool
+        logger.info(f"Assigning label {label_id} to card {card_id} via MCP")
+        assign_result = await nc_mcp_client.call_tool(
+            "deck_assign_label_to_card",
+            {
+                "board_id": board_id,
+                "stack_id": stack_id,
+                "card_id": card_id,
+                "label_id": label_id,
+            },
+        )
+
+        assert assign_result.isError is False, (
+            f"MCP label assignment failed: {assign_result.content}"
+        )
+        logger.info("Label assigned to card via MCP tool successfully")
+
+        # 2. Verify assignment via direct client
+        card = await nc_client.deck.get_card(board_id, stack_id, card_id)
+        if card.labels:
+            label_ids = [label.id for label in card.labels]
+            assert label_id in label_ids, "Label not found in card labels"
+        logger.info("Label assignment verified via direct client")
+
+        # 3. Remove label from card via MCP tool
+        logger.info(f"Removing label {label_id} from card {card_id} via MCP")
+        remove_result = await nc_mcp_client.call_tool(
+            "deck_remove_label_from_card",
+            {
+                "board_id": board_id,
+                "stack_id": stack_id,
+                "card_id": card_id,
+                "label_id": label_id,
+            },
+        )
+
+        assert remove_result.isError is False, (
+            f"MCP label removal failed: {remove_result.content}"
+        )
+        logger.info("Label removed from card via MCP tool successfully")
+
+        # 4. Verify removal via direct client
+        card = await nc_client.deck.get_card(board_id, stack_id, card_id)
+        if card.labels:
+            label_ids = [label.id for label in card.labels]
+            assert label_id not in label_ids, (
+                "Label still found in card labels after removal"
+            )
+        logger.info("Label removal verified via direct client")
+
+    finally:
+        # Clean up
+        await nc_client.deck.delete_label(board_id, label_id)
+        logger.info(f"Cleaned up label ID: {label_id}")
+
+
+# User Assignment Tests
+async def test_deck_card_user_assignment_mcp_tools(
+    nc_mcp_client: ClientSession,
+    nc_client: NextcloudClient,
+    temporary_board_with_card: tuple,
+):
+    """Test card-user assignment operations via MCP tools."""
+    board_data, stack_data, card_data = temporary_board_with_card
+    board_id = board_data["id"]
+    stack_id = stack_data["id"]
+    card_id = card_data["id"]
+
+    # Use the current user ID (admin in most test environments)
+    user_id = "admin"
+
+    # 1. Assign user to card via MCP tool
+    logger.info(f"Assigning user {user_id} to card {card_id} via MCP")
+    assign_result = await nc_mcp_client.call_tool(
+        "deck_assign_user_to_card",
+        {
+            "board_id": board_id,
+            "stack_id": stack_id,
+            "card_id": card_id,
+            "user_id": user_id,
+        },
+    )
+
+    assert assign_result.isError is False, (
+        f"MCP user assignment failed: {assign_result.content}"
+    )
+    logger.info("User assigned to card via MCP tool successfully")
+
+    # 2. Verify assignment via direct client
+    card = await nc_client.deck.get_card(board_id, stack_id, card_id)
+    if card.assignedUsers:
+        user_ids = []
+        for user in card.assignedUsers:
+            if hasattr(user, "participant"):
+                # It's a DeckAssignedUser with participant
+                user_ids.append(user.participant.uid)
+            elif hasattr(user, "uid"):
+                # It's a direct DeckUser
+                user_ids.append(user.uid)
+        assert user_id in user_ids, "User not found in card assigned users"
+    logger.info("User assignment verified via direct client")
+
+    # 3. Unassign user from card via MCP tool
+    logger.info(f"Unassigning user {user_id} from card {card_id} via MCP")
+    unassign_result = await nc_mcp_client.call_tool(
+        "deck_unassign_user_from_card",
+        {
+            "board_id": board_id,
+            "stack_id": stack_id,
+            "card_id": card_id,
+            "user_id": user_id,
+        },
+    )
+
+    assert unassign_result.isError is False, (
+        f"MCP user unassignment failed: {unassign_result.content}"
+    )
+    logger.info("User unassigned from card via MCP tool successfully")
+
+    # 4. Verify unassignment via direct client
+    card = await nc_client.deck.get_card(board_id, stack_id, card_id)
+    if card.assignedUsers:
+        user_ids = []
+        for user in card.assignedUsers:
+            if hasattr(user, "participant"):
+                # It's a DeckAssignedUser with participant
+                user_ids.append(user.participant.uid)
+            elif hasattr(user, "uid"):
+                # It's a direct DeckUser
+                user_ids.append(user.uid)
+        assert user_id not in user_ids, (
+            "User still found in card assigned users after removal"
+        )
+    logger.info("User unassignment verified via direct client")
+
+
+# Error handling tests
+async def test_deck_mcp_tools_error_handling(nc_mcp_client: ClientSession):
+    """Test error handling for deck MCP tools with invalid parameters."""
+    non_existent_id = 999999999
+
+    # Test stack operations with non-existent board
+    stack_result = await nc_mcp_client.call_tool(
+        "deck_create_stack",
+        {"board_id": non_existent_id, "title": "Should Fail", "order": 1},
+    )
+    assert stack_result.isError is True, (
+        "Expected error for stack creation on non-existent board"
+    )
+
+    # Test card operations with non-existent IDs
+    card_result = await nc_mcp_client.call_tool(
+        "deck_create_card",
+        {
+            "board_id": non_existent_id,
+            "stack_id": non_existent_id,
+            "title": "Should Fail",
+            "type": "plain",
+        },
+    )
+    assert card_result.isError is True, (
+        "Expected error for card creation with non-existent IDs"
+    )
+
+    # Test label operations with non-existent board
+    label_result = await nc_mcp_client.call_tool(
+        "deck_create_label",
+        {"board_id": non_existent_id, "title": "Should Fail", "color": "FF0000"},
+    )
+    assert label_result.isError is True, (
+        "Expected error for label creation on non-existent board"
+    )
+
+    logger.info("Error handling tests passed for deck MCP tools")
+
+
+# Resource template tests
+async def test_deck_mcp_resource_templates(nc_mcp_client: ClientSession):
+    """Test deck MCP resource templates are properly registered."""
+    templates = await nc_mcp_client.list_resource_templates()
+    template_uris = [template.uriTemplate for template in templates.resourceTemplates]
+
+    expected_templates = [
+        "nc://Deck/boards/{board_id}/stacks/{stack_id}",
+        "nc://Deck/boards/{board_id}/stacks/{stack_id}/cards/{card_id}",
+        "nc://Deck/boards/{board_id}/labels/{label_id}",
+    ]
+
+    for expected_template in expected_templates:
+        assert expected_template in template_uris, (
+            f"Expected template '{expected_template}' not found"
+        )
+        logger.info(f"Found expected deck resource template: {expected_template}")
+
+
+# Listing resource tests
+async def test_deck_mcp_listing_resources(
+    nc_mcp_client: ClientSession, temporary_board_with_card: tuple
+):
+    """Test deck MCP listing resources for stacks and cards."""
+    board_data, stack_data, card_data = temporary_board_with_card
+    board_id = board_data["id"]
+    stack_id = stack_data["id"]
+
+    # 1. Test listing stacks resource
+    logger.info(f"Reading stacks list via MCP resource for board {board_id}")
+    stacks_resource_result = await nc_mcp_client.read_resource(
+        f"nc://Deck/boards/{board_id}/stacks"
+    )
+    stacks_resource_data = json.loads(stacks_resource_result.contents[0].text)
+    assert isinstance(stacks_resource_data, list)
+
+    # Verify our stack is in the resource list
+    stack_ids = [stack["id"] for stack in stacks_resource_data]
+    assert stack_id in stack_ids, "Stack not found in stacks resource list"
+    logger.info("Stack found in stacks resource list")
+
+    # 2. Test listing cards resource
+    logger.info(f"Reading cards list via MCP resource for stack {stack_id}")
+    cards_resource_result = await nc_mcp_client.read_resource(
+        f"nc://Deck/boards/{board_id}/stacks/{stack_id}/cards"
+    )
+    cards_resource_data = json.loads(cards_resource_result.contents[0].text)
+    assert isinstance(cards_resource_data, list)
+
+    # Verify our card is in the resource list
+    card_ids = [card["id"] for card in cards_resource_data]
+    assert card_data["id"] in card_ids, "Card not found in cards resource list"
+    logger.info("Card found in cards resource list")
+
+    # 3. Test listing labels resource
+    logger.info(f"Reading labels list via MCP resource for board {board_id}")
+    labels_resource_result = await nc_mcp_client.read_resource(
+        f"nc://Deck/boards/{board_id}/labels"
+    )
+    labels_resource_data = json.loads(labels_resource_result.contents[0].text)
+    assert isinstance(labels_resource_data, list)
+    logger.info("Labels resource read successfully")

tests/server/test_error_propagation.py

@@ -1,23 +1,27 @@
 """Test error propagation in the MCP server for various error scenarios."""
 
 import logging
-from mcp import ClientSession
-from mcp.shared.exceptions import McpError
 
 import pytest
+from mcp import ClientSession
 
 logger = logging.getLogger(__name__)
 
-
-@pytest.mark.integration
-async def test_missing_note_resource_error(nc_mcp_client: ClientSession):
-    """Test that accessing a non-existent note resource returns proper error."""
-    # Try to get a non-existent note via resource - should raise McpError with improved message
-    with pytest.raises(McpError, match=r"Note 999999 not found"):
-        await nc_mcp_client.read_resource("nc://Notes/999999")
+# Mark all tests in this module as integration tests
+pytestmark = pytest.mark.integration
+
+
+async def test_missing_note_tool_error(nc_mcp_client: ClientSession):
+    """Test that accessing a non-existent note via tool returns proper error."""
+    # Try to get a non-existent note via tool - should return error response
+    response = await nc_mcp_client.call_tool("nc_notes_get_note", {"note_id": 999999})
+
+    # Should return error response (not raise exception) for tools
+    assert response is not None
+    assert response.isError is True
+    assert "Note 999999 not found" in response.content[0].text
 
 
-@pytest.mark.integration
 async def test_delete_missing_note_tool_error(nc_mcp_client: ClientSession):
     """Test that deleting a non-existent note returns proper error."""
     # Try to delete a non-existent note - should return error response
@@ -31,7 +35,6 @@ async def test_delete_missing_note_tool_error(nc_mcp_client: ClientSession):
     assert "Note 999999 not found" in response.content[0].text
 
 
-@pytest.mark.integration
 async def test_search_with_empty_query(nc_mcp_client: ClientSession):
     """Test search behavior with empty query."""
     # Search with empty query
@@ -44,7 +47,6 @@ async def test_search_with_empty_query(nc_mcp_client: ClientSession):
     assert response.isError is False
 
 
-@pytest.mark.integration
 async def test_tool_missing_required_parameters(nc_mcp_client: ClientSession):
     """Test calling a tool with missing required parameters."""
     # Try to create note with missing parameters
@@ -63,7 +65,6 @@ async def test_tool_missing_required_parameters(nc_mcp_client: ClientSession):
     )
 
 
-@pytest.mark.integration
 async def test_update_note_with_invalid_etag(nc_mcp_client: ClientSession, nc_client):
     """Test updating a note with invalid ETag."""
     # First create a note
@@ -95,7 +96,6 @@ async def test_update_note_with_invalid_etag(nc_mcp_client: ClientSession, nc_cl
         await nc_client.notes.delete_note(note_id)
 
 
-@pytest.mark.integration
 async def test_calendar_missing_calendar_error(nc_mcp_client: ClientSession):
     """Test calendar operations with non-existent calendar."""
     # Try to create event in non-existent calendar
@@ -124,7 +124,6 @@ async def test_calendar_missing_calendar_error(nc_mcp_client: ClientSession):
         assert response.isError is True
 
 
-@pytest.mark.integration
 async def test_webdav_read_missing_file_error(nc_mcp_client: ClientSession):
     """Test WebDAV operations with non-existent file."""
     # Try to read a non-existent file
@@ -148,7 +147,6 @@ async def test_webdav_read_missing_file_error(nc_mcp_client: ClientSession):
         assert response.isError is True
 
 
-@pytest.mark.integration
 async def test_tables_missing_table_error(nc_mcp_client: ClientSession):
     """Test Tables operations with non-existent table."""
     # Try to get schema of non-existent table

tests/server/test_mcp.py

@@ -68,7 +68,8 @@ async def test_mcp_connectivity(nc_mcp_client: ClientSession):
         template_uris.append(template.uriTemplate)
 
     # Verify expected resource templates
-    expected_templates = ["nc://Notes/{note_id}/attachments/{attachment_filename}"]
+    # Note: Notes attachments are now handled via tools, not resource templates
+    expected_templates = []
 
     for expected_template in expected_templates:
         assert expected_template in template_uris, (
@@ -140,9 +141,11 @@ async def test_mcp_notes_crud_workflow(
 
         # 3. Read note via MCP
         logger.info(f"Reading note via MCP: {note_id}")
-        read_result = await nc_mcp_client.read_resource(f"nc://Notes/{note_id}")
-        assert len(read_result.contents) == 1, "Expected exactly one content item"
-        read_note_data = json.loads(read_result.contents[0].text)
+        read_result = await nc_mcp_client.call_tool(
+            "nc_notes_get_note", {"note_id": note_id}
+        )
+        read_note_data = read_result.content[0].text
+        read_note_data = json.loads(read_note_data)
 
         assert read_note_data["title"] == test_title
         assert read_note_data["content"] == test_content

tests/server/test_mcp_oauth.py

@@ -0,0 +1,59 @@
+import json
+import logging
+import pytest
+
+logger = logging.getLogger(__name__)
+
+pytestmark = [pytest.mark.integration, pytest.mark.oauth]
+
+
+async def test_mcp_oauth_server_connection(nc_mcp_oauth_client):
+    """Test connection to OAuth-enabled MCP server."""
+    result = await nc_mcp_oauth_client.list_tools()
+    assert result is not None
+    assert len(result.tools) > 0
+
+    logger.info(f"OAuth MCP server has {len(result.tools)} tools available")
+
+
+async def test_mcp_oauth_tool_execution(nc_mcp_oauth_client):
+    """Test executing a tool on the OAuth-enabled MCP server."""
+    import json
+
+    # Example: Execute the 'nc_notes_search_notes' tool
+    result = await nc_mcp_oauth_client.call_tool(
+        "nc_notes_search_notes", arguments={"query": ""}
+    )
+
+    assert result.isError is False, f"Tool execution failed: {result.content}"
+    assert result.content is not None
+    response_data = json.loads(result.content[0].text)
+
+    # The search response should have a 'results' field containing the list
+    assert "results" in response_data
+    assert isinstance(response_data["results"], list)
+
+    logger.info(
+        f"Successfully executed 'nc_notes_search_notes' tool on OAuth MCP server and got {len(response_data['results'])} notes."
+    )
+
+
+async def test_mcp_oauth_client_with_playwright(nc_mcp_oauth_client_playwright):
+    """Test that MCP OAuth client via Playwright can execute tools."""
+
+    # Test: Execute the 'nc_notes_search_notes' tool
+    result = await nc_mcp_oauth_client_playwright.call_tool(
+        "nc_notes_search_notes", arguments={"query": ""}
+    )
+
+    assert result.isError is False, f"Tool execution failed: {result.content}"
+    assert result.content is not None
+    response_data = json.loads(result.content[0].text)
+
+    # The search response should have a 'results' field containing the list
+    assert "results" in response_data
+    assert isinstance(response_data["results"], list)
+
+    logger.info(
+        f"Successfully executed 'nc_notes_search_notes' tool on Playwright OAuth MCP server and got {len(response_data['results'])} notes."
+    )

tests/server/test_oauth_deck_permissions.py

@@ -0,0 +1,358 @@
+"""
+Multi-user OAuth tests for Nextcloud Deck board permissions.
+
+Tests verify that the MCP server respects Nextcloud Deck board ACL permissions
+when accessed via OAuth authentication with different users.
+"""
+
+import json
+import logging
+
+import pytest
+
+logger = logging.getLogger(__name__)
+
+pytestmark = [pytest.mark.integration, pytest.mark.oauth]
+
+
+async def add_board_acl(nc_client, board_id: int, user: str, permission_type: int = 0):
+    """
+    Helper to add ACL entry to a Deck board.
+
+    Args:
+        nc_client: Admin NextcloudClient
+        board_id: Board ID
+        user: Username to grant access
+        permission_type: 0=view, 1=edit, 2=manage
+
+    Returns:
+        ACL entry ID
+    """
+    acl = await nc_client.deck.add_acl_rule(
+        board_id=board_id,
+        type=0,  # 0 = user, 1 = group
+        participant=user,
+        permission_edit=permission_type >= 1,
+        permission_share=permission_type >= 2,
+        permission_manage=permission_type >= 2,
+    )
+    logger.info(f"Added ACL for board {board_id}: {user} (type={permission_type})")
+    return acl.id
+
+
+async def delete_board_acl(nc_client, board_id: int, acl_id: int):
+    """Helper to delete a board ACL entry."""
+    await nc_client.deck.delete_acl_rule(board_id, acl_id)
+    logger.info(f"Deleted ACL {acl_id} from board {board_id}")
+
+
+@pytest.mark.asyncio
+async def test_deck_board_view_permissions(
+    nc_client, alice_mcp_client, bob_mcp_client, diana_mcp_client
+):
+    """
+    Test that Deck boards respect view permissions.
+
+    Scenario:
+    1. Admin creates a board as alice
+    2. Admin adds bob to board with view-only permissions
+    3. Bob can view the board via MCP tools
+    4. Diana cannot access the board (no ACL entry)
+    """
+    # Create a board as alice
+    logger.info("Creating Deck board as alice...")
+    board = await nc_client.deck.create_board(
+        "Alice's Shared Board - View Test", "FF0000"
+    )
+    board_id = board.id
+
+    bob_acl_id = None
+
+    try:
+        # Add bob to board with view-only permission
+        logger.info("Adding bob to board with view permission...")
+        bob_acl_id = await add_board_acl(nc_client, board_id, "bob", permission_type=0)
+
+        # Test: Bob can view the board via MCP
+        logger.info("Bob attempting to list boards via MCP...")
+        result = await bob_mcp_client.call_tool("deck_get_boards", arguments={})
+
+        if not result.isError:
+            response_data = json.loads(result.content[0].text)
+            # The response is directly a list of boards
+            if not isinstance(response_data, list):
+                response_data = [response_data] if response_data else []
+            board_ids = [b["id"] for b in response_data]
+            logger.info(f"Bob can see {len(response_data)} boards: {board_ids}")
+
+            # Bob should see the shared board
+            if board_id in board_ids:
+                logger.info(f"Bob can see shared board {board_id}")
+            else:
+                logger.warning(f"Bob cannot see shared board {board_id}")
+        else:
+            logger.warning(f"Bob could not list boards: {result.content}")
+
+        # Test: Diana cannot see the board
+        logger.info("Diana attempting to list boards via MCP...")
+        result = await diana_mcp_client.call_tool("deck_get_boards", arguments={})
+
+        if not result.isError:
+            response_data = json.loads(result.content[0].text)
+            # The response is directly a list of boards
+            if not isinstance(response_data, list):
+                response_data = [response_data] if response_data else []
+            board_ids = [b["id"] for b in response_data]
+            logger.info(f"Diana can see {len(response_data)} boards")
+
+            # Diana should NOT see the board
+            assert board_id not in board_ids, "Diana should not see board without ACL"
+            logger.info("Diana correctly cannot see board without ACL")
+        else:
+            logger.warning(f"Diana could not list boards: {result.content}")
+
+    finally:
+        # Cleanup
+        if bob_acl_id:
+            await delete_board_acl(nc_client, board_id, bob_acl_id)
+        logger.info(f"Deleting board {board_id}")
+        await nc_client.deck.delete_board(board_id)
+
+
+@pytest.mark.asyncio
+async def test_deck_board_edit_permissions(
+    nc_client, alice_mcp_client, charlie_mcp_client, bob_mcp_client
+):
+    """
+    Test that Deck boards respect edit permissions.
+
+    Scenario:
+    1. Admin creates a board as alice with a stack
+    2. Admin adds charlie with edit permission
+    3. Admin adds bob with view-only permission
+    4. Charlie can create cards via MCP tools
+    5. Bob cannot create cards
+    """
+    # Create a board as alice
+    logger.info("Creating Deck board as alice...")
+    board = await nc_client.deck.create_board(
+        "Alice's Shared Board - Edit Test", "00FF00"
+    )
+    board_id = board.id
+
+    # Create a stack in the board
+    logger.info("Creating stack in board...")
+    stack = await nc_client.deck.create_stack(board_id, "Test Stack", 1)
+    stack_id = stack.id
+
+    charlie_acl_id = None
+    bob_acl_id = None
+
+    try:
+        # Add charlie with edit permission
+        logger.info("Adding charlie to board with edit permission...")
+        charlie_acl_id = await add_board_acl(
+            nc_client, board_id, "charlie", permission_type=1
+        )
+
+        # Add bob with view-only permission
+        logger.info("Adding bob to board with view permission...")
+        bob_acl_id = await add_board_acl(nc_client, board_id, "bob", permission_type=0)
+
+        # Test: Charlie can create a card
+        logger.info("Charlie attempting to create card via MCP...")
+        result = await charlie_mcp_client.call_tool(
+            "deck_create_card",
+            arguments={
+                "board_id": board_id,
+                "stack_id": stack_id,
+                "title": "Charlie's Card",
+                "description": "Created by Charlie with edit permission",
+            },
+        )
+
+        if not result.isError:
+            response_data = json.loads(result.content[0].text)
+            card_id = response_data.get("id")
+            logger.info(f"Charlie successfully created card {card_id}")
+
+            # Cleanup the card
+            await nc_client.deck.delete_card(board_id, stack_id, card_id)
+        else:
+            logger.warning(f"Charlie could not create card: {result.content}")
+
+        # Test: Bob attempts to create a card (should fail)
+        logger.info("Bob attempting to create card via MCP...")
+        result = await bob_mcp_client.call_tool(
+            "deck_create_card",
+            arguments={
+                "board_id": board_id,
+                "stack_id": stack_id,
+                "title": "Bob's Card",
+                "description": "Bob trying to create a card",
+            },
+        )
+
+        if result.isError:
+            logger.info("Bob correctly denied card creation (view-only)")
+        else:
+            logger.warning("Bob unexpectedly succeeded in creating card")
+            # Cleanup if bob somehow created a card
+            response_data = json.loads(result.content[0].text)
+            if "id" in response_data:
+                await nc_client.deck.delete_card(
+                    board_id, stack_id, response_data["id"]
+                )
+
+    finally:
+        # Cleanup
+        if charlie_acl_id:
+            await delete_board_acl(nc_client, board_id, charlie_acl_id)
+        if bob_acl_id:
+            await delete_board_acl(nc_client, board_id, bob_acl_id)
+        logger.info(f"Deleting board {board_id}")
+        await nc_client.deck.delete_board(board_id)
+
+
+@pytest.mark.asyncio
+async def test_deck_board_manage_permissions(
+    nc_client, alice_mcp_client, charlie_mcp_client
+):
+    """
+    Test that Deck boards respect manage permissions.
+
+    Scenario:
+    1. Admin creates a board as alice
+    2. Admin adds charlie with manage permission
+    3. Charlie can create stacks and modify board settings
+    """
+    # Create a board as alice
+    logger.info("Creating Deck board as alice...")
+    board = await nc_client.deck.create_board(
+        "Alice's Shared Board - Manage Test", "0000FF"
+    )
+    board_id = board.id
+
+    charlie_acl_id = None
+
+    try:
+        # Add charlie with manage permission
+        logger.info("Adding charlie to board with manage permission...")
+        charlie_acl_id = await add_board_acl(
+            nc_client, board_id, "charlie", permission_type=2
+        )
+
+        # Test: Charlie can create a stack
+        logger.info("Charlie attempting to create stack via MCP...")
+        result = await charlie_mcp_client.call_tool(
+            "deck_create_stack",
+            arguments={"board_id": board_id, "title": "Charlie's Stack", "order": 1},
+        )
+
+        if not result.isError:
+            response_data = json.loads(result.content[0].text)
+            stack_id = response_data.get("id")
+            logger.info(f"Charlie successfully created stack {stack_id}")
+
+            # Cleanup the stack
+            await nc_client.deck.delete_stack(board_id, stack_id)
+        else:
+            logger.warning(f"Charlie could not create stack: {result.content}")
+
+        # Test: Charlie can delete a stack (manage permission)
+        logger.info("Charlie attempting to delete stack via MCP...")
+        # First create a temporary stack to delete
+        temp_stack = await nc_client.deck.create_stack(
+            board_id, "Temp Stack for Deletion", 99
+        )
+
+        result = await charlie_mcp_client.call_tool(
+            "deck_delete_stack",
+            arguments={"board_id": board_id, "stack_id": temp_stack.id},
+        )
+
+        if not result.isError:
+            logger.info("Charlie successfully deleted stack")
+        else:
+            logger.warning(f"Charlie could not delete stack: {result.content}")
+            # Cleanup if deletion via MCP failed
+            try:
+                await nc_client.deck.delete_stack(board_id, temp_stack.id)
+            except Exception:
+                pass
+
+    finally:
+        # Cleanup
+        if charlie_acl_id:
+            await delete_board_acl(nc_client, board_id, charlie_acl_id)
+        logger.info(f"Deleting board {board_id}")
+        await nc_client.deck.delete_board(board_id)
+
+
+@pytest.mark.asyncio
+async def test_deck_user_isolation(nc_client, alice_mcp_client, bob_mcp_client):
+    """
+    Test that users can only see their own boards when not shared.
+
+    Scenario:
+    1. Admin creates a board as alice (not shared)
+    2. Admin creates a board as bob (not shared)
+    3. Alice can only see her own board
+    4. Bob can only see his own board
+    """
+    # Create alice's board
+    logger.info("Creating alice's private board...")
+    alice_board = await nc_client.deck.create_board("Alice's Private Board", "FF00FF")
+    alice_board_id = alice_board.id
+
+    # Create bob's board
+    logger.info("Creating bob's private board...")
+    bob_board = await nc_client.deck.create_board("Bob's Private Board", "00FFFF")
+    bob_board_id = bob_board.id
+
+    try:
+        # Test: Alice lists boards
+        logger.info("Alice listing boards via MCP...")
+        result = await alice_mcp_client.call_tool("deck_get_boards", arguments={})
+
+        if not result.isError:
+            response_data = json.loads(result.content[0].text)
+            # The response is directly a list of boards
+            if not isinstance(response_data, list):
+                response_data = [response_data] if response_data else []
+            board_ids = [b["id"] for b in response_data]
+            logger.info(f"Alice can see boards: {board_ids}")
+
+            # Alice should NOT see Bob's board
+            assert bob_board_id not in board_ids, (
+                "Alice should not see Bob's private board"
+            )
+        else:
+            logger.warning(f"Alice could not list boards: {result.content}")
+
+        # Test: Bob lists boards
+        logger.info("Bob listing boards via MCP...")
+        result = await bob_mcp_client.call_tool("deck_get_boards", arguments={})
+
+        if not result.isError:
+            response_data = json.loads(result.content[0].text)
+            # The response is directly a list of boards
+            if not isinstance(response_data, list):
+                response_data = [response_data] if response_data else []
+            board_ids = [b["id"] for b in response_data]
+            logger.info(f"Bob can see boards: {board_ids}")
+
+            # Bob should NOT see Alice's board
+            assert alice_board_id not in board_ids, (
+                "Bob should not see Alice's private board"
+            )
+        else:
+            logger.warning(f"Bob could not list boards: {result.content}")
+
+        logger.info("User isolation test passed: users can only see their own boards")
+
+    finally:
+        # Cleanup
+        logger.info("Cleaning up test boards...")
+        await nc_client.deck.delete_board(alice_board_id)
+        await nc_client.deck.delete_board(bob_board_id)

tests/server/test_oauth_file_permissions.py

@@ -0,0 +1,425 @@
+"""
+Multi-user OAuth tests for Nextcloud WebDAV file permissions.
+
+Tests verify that the MCP server respects Nextcloud file sharing permissions
+when accessed via OAuth authentication with different users.
+
+All operations (file creation, sharing, access) are performed through MCP tools
+to ensure the MCP server properly supports multi-user scenarios.
+"""
+
+import json
+import logging
+
+import pytest
+
+logger = logging.getLogger(__name__)
+
+pytestmark = [pytest.mark.integration, pytest.mark.oauth]
+
+
+@pytest.mark.asyncio
+async def test_file_share_read_permissions(
+    alice_mcp_client, bob_mcp_client, diana_mcp_client
+):
+    """
+    Test that shared files respect read permissions.
+
+    Scenario:
+    1. Alice creates a file via MCP
+    2. Alice shares the file with Bob (read-only) via MCP
+    3. Bob can read the file via MCP tools
+    4. Diana cannot access the file (no share)
+    """
+    file_path = "/alice_shared_file_read.txt"
+    file_content = "This file is shared with Bob for reading only."
+
+    # Alice creates a file
+    logger.info(f"Alice creating file: {file_path}")
+    result = await alice_mcp_client.call_tool(
+        "nc_webdav_write_file",
+        arguments={"path": file_path, "content": file_content},
+    )
+    assert not result.isError, f"Alice failed to create file: {result.content}"
+
+    share_id = None
+
+    try:
+        # Alice shares the file with bob (read-only, permissions=1)
+        logger.info("Alice sharing file with bob (read-only)...")
+        result = await alice_mcp_client.call_tool(
+            "nc_share_create",
+            arguments={
+                "path": file_path,
+                "share_with": "bob",
+                "share_type": 0,
+                "permissions": 1,
+            },
+        )
+        assert not result.isError, f"Alice failed to create share: {result.content}"
+        share_data = json.loads(result.content[0].text)
+        share_id = share_data["id"]
+        logger.info(f"Created share {share_id}")
+
+        # Test: Bob reads the file via MCP
+        logger.info("Bob attempting to read file via MCP...")
+        result = await bob_mcp_client.call_tool(
+            "nc_webdav_read_file", arguments={"path": file_path}
+        )
+
+        # Bob should be able to read the shared file
+        if not result.isError:
+            response_data = json.loads(result.content[0].text)
+            logger.info(
+                f"Bob successfully read file: {response_data.get('content', '')[:50]}..."
+            )
+            assert "content" in response_data
+            assert file_content in response_data["content"]
+        else:
+            logger.warning(f"Bob could not read file: {result.content}")
+            # This might fail if the share path is different for bob
+
+        # Test: Diana attempts to read the file
+        logger.info("Diana attempting to read file via MCP...")
+        result = await diana_mcp_client.call_tool(
+            "nc_webdav_read_file", arguments={"path": file_path}
+        )
+
+        # Diana should NOT be able to read (no share)
+        if result.isError:
+            logger.info("Diana correctly denied access to unshared file")
+        else:
+            logger.warning("Diana unexpectedly could read unshared file")
+
+    finally:
+        # Cleanup - Alice deletes the share and file
+        if share_id:
+            logger.info(f"Alice deleting share {share_id}")
+            await alice_mcp_client.call_tool(
+                "nc_share_delete", arguments={"share_id": share_id}
+            )
+        logger.info(f"Alice deleting file {file_path}")
+        await alice_mcp_client.call_tool(
+            "nc_webdav_delete_resource", arguments={"path": file_path}
+        )
+
+
+@pytest.mark.asyncio
+async def test_file_share_write_permissions(
+    alice_mcp_client, charlie_mcp_client, bob_mcp_client
+):
+    """
+    Test that shared files respect write permissions.
+
+    Scenario:
+    1. Alice creates a file via MCP
+    2. Alice shares the file with Charlie (edit permission) via MCP
+    3. Alice shares the file with Bob (read-only) via MCP
+    4. Charlie can edit the file via MCP tools
+    5. Bob cannot edit the file
+    """
+    file_path = "/alice_shared_file_write.txt"
+    file_content = "This file is shared with Charlie for editing."
+
+    logger.info(f"Alice creating file: {file_path}")
+    result = await alice_mcp_client.call_tool(
+        "nc_webdav_write_file",
+        arguments={"path": file_path, "content": file_content},
+    )
+    assert not result.isError, f"Alice failed to create file: {result.content}"
+
+    charlie_share_id = None
+    bob_share_id = None
+
+    try:
+        # Alice shares with Charlie (read+write, permissions=3)
+        logger.info("Alice sharing file with Charlie (edit permission)...")
+        result = await alice_mcp_client.call_tool(
+            "nc_share_create",
+            arguments={
+                "path": file_path,
+                "share_with": "charlie",
+                "share_type": 0,
+                "permissions": 3,
+            },
+        )
+        assert not result.isError, (
+            f"Alice failed to share with Charlie: {result.content}"
+        )
+        charlie_share_data = json.loads(result.content[0].text)
+        charlie_share_id = charlie_share_data["id"]
+        logger.info(f"Created share {charlie_share_id} for Charlie")
+
+        # Alice shares with Bob (read-only, permissions=1)
+        logger.info("Alice sharing file with Bob (read-only)...")
+        result = await alice_mcp_client.call_tool(
+            "nc_share_create",
+            arguments={
+                "path": file_path,
+                "share_with": "bob",
+                "share_type": 0,
+                "permissions": 1,
+            },
+        )
+        assert not result.isError, f"Alice failed to share with Bob: {result.content}"
+        bob_share_data = json.loads(result.content[0].text)
+        bob_share_id = bob_share_data["id"]
+        logger.info(f"Created share {bob_share_id} for Bob")
+
+        # Test: Charlie can write to the file
+        logger.info("Charlie attempting to write to file via MCP...")
+        updated_content = f"{file_content}\nCharlie added this line."
+        result = await charlie_mcp_client.call_tool(
+            "nc_webdav_write_file",
+            arguments={"path": file_path, "content": updated_content},
+        )
+
+        if not result.isError:
+            logger.info("Charlie successfully wrote to file")
+        else:
+            logger.warning(f"Charlie could not write to file: {result.content}")
+
+        # Test: Bob attempts to write (should fail)
+        logger.info("Bob attempting to write to file via MCP...")
+        result = await bob_mcp_client.call_tool(
+            "nc_webdav_write_file",
+            arguments={"path": file_path, "content": "Bob tries to overwrite this."},
+        )
+
+        # Bob should be denied
+        if result.isError:
+            logger.info("Bob correctly denied write access")
+        else:
+            logger.warning("Bob unexpectedly succeeded in writing (permissions issue?)")
+
+    finally:
+        # Cleanup - Alice deletes shares and file
+        if charlie_share_id:
+            logger.info(f"Alice deleting Charlie's share {charlie_share_id}")
+            await alice_mcp_client.call_tool(
+                "nc_share_delete", arguments={"share_id": charlie_share_id}
+            )
+        if bob_share_id:
+            logger.info(f"Alice deleting Bob's share {bob_share_id}")
+            await alice_mcp_client.call_tool(
+                "nc_share_delete", arguments={"share_id": bob_share_id}
+            )
+        logger.info(f"Alice deleting file {file_path}")
+        await alice_mcp_client.call_tool(
+            "nc_webdav_delete_resource", arguments={"path": file_path}
+        )
+
+
+@pytest.mark.asyncio
+async def test_file_list_permissions(alice_mcp_client, bob_mcp_client):
+    """
+    Test that file listing respects share permissions.
+
+    Scenario:
+    1. Alice creates her private file via MCP
+    2. Bob creates his private file via MCP
+    3. Alice creates a file and shares it with Bob via MCP
+    4. Alice can list her own files + shared files
+    5. Bob can list his own files + shared files from Alice
+    """
+    alice_file = "/alice_private_file.txt"
+    bob_file = "/bob_private_file.txt"
+    shared_file = "/alice_shared_with_bob.txt"
+
+    # Alice creates her private file
+    logger.info(f"Alice creating private file: {alice_file}")
+    result = await alice_mcp_client.call_tool(
+        "nc_webdav_write_file",
+        arguments={"path": alice_file, "content": "Alice's private file"},
+    )
+    assert not result.isError, f"Alice failed to create file: {result.content}"
+
+    # Bob creates his private file
+    logger.info(f"Bob creating private file: {bob_file}")
+    result = await bob_mcp_client.call_tool(
+        "nc_webdav_write_file",
+        arguments={"path": bob_file, "content": "Bob's private file"},
+    )
+    assert not result.isError, f"Bob failed to create file: {result.content}"
+
+    # Alice creates a shared file
+    logger.info(f"Alice creating shared file: {shared_file}")
+    result = await alice_mcp_client.call_tool(
+        "nc_webdav_write_file",
+        arguments={"path": shared_file, "content": "Shared file content"},
+    )
+    assert not result.isError, f"Alice failed to create shared file: {result.content}"
+
+    share_id = None
+
+    try:
+        # Alice shares the file with Bob
+        logger.info("Alice sharing file with Bob...")
+        result = await alice_mcp_client.call_tool(
+            "nc_share_create",
+            arguments={
+                "path": shared_file,
+                "share_with": "bob",
+                "share_type": 0,
+                "permissions": 1,
+            },
+        )
+        assert not result.isError, f"Alice failed to create share: {result.content}"
+        share_data = json.loads(result.content[0].text)
+        share_id = share_data["id"]
+
+        # Test: Alice lists files in root
+        logger.info("Alice listing files via MCP...")
+        result = await alice_mcp_client.call_tool(
+            "nc_webdav_list_directory", arguments={"path": "/"}
+        )
+
+        if not result.isError:
+            response_data = json.loads(result.content[0].text)
+            if not isinstance(response_data, list):
+                response_data = [response_data] if response_data else []
+            file_names = [f["name"] for f in response_data]
+            logger.info(f"Alice can see files: {file_names}")
+
+            # Alice should see her own files
+            # Note: Exact assertions depend on test isolation
+        else:
+            logger.warning(f"Alice could not list files: {result.content}")
+
+        # Test: Bob lists files in root
+        logger.info("Bob listing files via MCP...")
+        result = await bob_mcp_client.call_tool(
+            "nc_webdav_list_directory", arguments={"path": "/"}
+        )
+
+        if not result.isError:
+            response_data = json.loads(result.content[0].text)
+            if not isinstance(response_data, list):
+                response_data = [response_data] if response_data else []
+            file_names = [f["name"] for f in response_data]
+            logger.info(f"Bob can see files: {file_names}")
+
+            # Bob should see his own file, but not Alice's private file
+            # Bob may see shared files in his shared folder or via different path
+        else:
+            logger.warning(f"Bob could not list files: {result.content}")
+
+    finally:
+        # Cleanup
+        if share_id:
+            logger.info(f"Alice deleting share {share_id}")
+            await alice_mcp_client.call_tool(
+                "nc_share_delete", arguments={"share_id": share_id}
+            )
+
+        logger.info("Cleaning up Alice's files...")
+        await alice_mcp_client.call_tool(
+            "nc_webdav_delete_resource", arguments={"path": alice_file}
+        )
+        await alice_mcp_client.call_tool(
+            "nc_webdav_delete_resource", arguments={"path": shared_file}
+        )
+
+        logger.info("Cleaning up Bob's files...")
+        await bob_mcp_client.call_tool(
+            "nc_webdav_delete_resource", arguments={"path": bob_file}
+        )
+
+
+@pytest.mark.asyncio
+async def test_folder_share_permissions(alice_mcp_client, bob_mcp_client):
+    """
+    Test that folder sharing works correctly.
+
+    Scenario:
+    1. Alice creates a folder via MCP
+    2. Alice creates files in the folder via MCP
+    3. Alice shares the folder with Bob via MCP
+    4. Bob can access files in the shared folder via MCP
+    """
+    folder_path = "/alice_shared_folder"
+    file_in_folder = f"{folder_path}/document.txt"
+    file_content = "This is a document in Alice's shared folder"
+
+    # Alice creates folder
+    logger.info(f"Alice creating folder: {folder_path}")
+    result = await alice_mcp_client.call_tool(
+        "nc_webdav_create_directory", arguments={"path": folder_path}
+    )
+    assert not result.isError, f"Alice failed to create folder: {result.content}"
+
+    # Alice creates file in folder
+    logger.info(f"Alice creating file in folder: {file_in_folder}")
+    result = await alice_mcp_client.call_tool(
+        "nc_webdav_write_file",
+        arguments={"path": file_in_folder, "content": file_content},
+    )
+    assert not result.isError, f"Alice failed to create file: {result.content}"
+
+    share_id = None
+
+    try:
+        # Alice shares the folder with Bob
+        logger.info("Alice sharing folder with Bob...")
+        result = await alice_mcp_client.call_tool(
+            "nc_share_create",
+            arguments={
+                "path": folder_path,
+                "share_with": "bob",
+                "share_type": 0,
+                "permissions": 1,
+            },
+        )
+        assert not result.isError, f"Alice failed to create share: {result.content}"
+        share_data = json.loads(result.content[0].text)
+        share_id = share_data["id"]
+        logger.info(f"Created folder share {share_id}")
+
+        # Test: Bob lists the shared folder
+        logger.info("Bob attempting to list shared folder via MCP...")
+        result = await bob_mcp_client.call_tool(
+            "nc_webdav_list_directory", arguments={"path": folder_path}
+        )
+
+        if not result.isError:
+            response_data = json.loads(result.content[0].text)
+            if not isinstance(response_data, list):
+                response_data = [response_data] if response_data else []
+            logger.info(f"Bob can see {len(response_data)} files in shared folder")
+
+            # Bob should see the file in the shared folder
+            file_names = [f["name"] for f in response_data]
+            assert "document.txt" in file_names, (
+                "Bob should see the file in shared folder"
+            )
+        else:
+            logger.warning(f"Bob could not list shared folder: {result.content}")
+
+        # Test: Bob reads the file in the shared folder
+        logger.info("Bob attempting to read file in shared folder via MCP...")
+        result = await bob_mcp_client.call_tool(
+            "nc_webdav_read_file", arguments={"path": file_in_folder}
+        )
+
+        if not result.isError:
+            response_data = json.loads(result.content[0].text)
+            logger.info("Bob successfully read file in shared folder")
+            assert "content" in response_data
+            assert file_content in response_data["content"]
+        else:
+            logger.warning(
+                f"Bob could not read file in shared folder: {result.content}"
+            )
+
+    finally:
+        # Cleanup - Alice deletes the share and folder
+        if share_id:
+            logger.info(f"Alice deleting share {share_id}")
+            await alice_mcp_client.call_tool(
+                "nc_share_delete", arguments={"share_id": share_id}
+            )
+
+        logger.info("Alice cleaning up test folder...")
+        await alice_mcp_client.call_tool(
+            "nc_webdav_delete_resource", arguments={"path": folder_path}
+        )

tests/server/test_oauth_notes_permissions.py

@@ -0,0 +1,260 @@
+"""
+Multi-user OAuth tests for Nextcloud Notes permissions.
+
+Tests verify that the MCP server respects Nextcloud Notes sharing permissions
+when accessed via OAuth authentication with different users.
+"""
+
+import json
+import logging
+
+import pytest
+
+logger = logging.getLogger(__name__)
+
+pytestmark = [pytest.mark.integration, pytest.mark.oauth]
+
+
+@pytest.mark.asyncio
+async def test_notes_share_read_permissions(
+    nc_client, alice_mcp_client, bob_mcp_client, diana_mcp_client
+):
+    """
+    Test that shared notes respect read permissions.
+
+    Scenario:
+    1. Admin creates a note as alice
+    2. Admin shares the note with bob (read-only)
+    3. Bob can read the note via MCP tools
+    4. Diana cannot access the note (no share)
+    """
+    # Create a note as alice (using admin client to set up data)
+    note_title = "Alice's Shared Note - Read Test"
+    note_content = "This note is shared with Bob for reading only."
+    note_category = "SharedNotes"
+
+    logger.info("Creating note as alice...")
+    created_note = await nc_client.notes.create_note(
+        title=note_title, content=note_content, category=note_category
+    )
+    note_id = created_note.get("id")
+
+    try:
+        # TODO: Share the note with bob (read-only)
+        # Note: Nextcloud Notes API doesn't have direct sharing endpoints
+        # Sharing is typically done at the folder level via WebDAV
+        # For now, this test documents the expected behavior
+
+        # Test: Bob searches for notes via MCP
+        logger.info("Bob searching for notes via MCP...")
+        result = await bob_mcp_client.call_tool(
+            "nc_notes_search_notes", arguments={"query": "Alice's Shared"}
+        )
+
+        assert result.isError is False, f"Bob's search failed: {result.content}"
+        response_data = json.loads(result.content[0].text)
+
+        # Bob should see the shared note in search results
+        # (assuming proper share setup)
+        assert "results" in response_data
+        logger.info(f"Bob found {len(response_data['results'])} notes")
+
+        # Test: Diana searches for the same note
+        logger.info("Diana searching for notes via MCP...")
+        result = await diana_mcp_client.call_tool(
+            "nc_notes_search_notes", arguments={"query": "Alice's Shared"}
+        )
+
+        assert result.isError is False
+        response_data = json.loads(result.content[0].text)
+
+        # Diana should NOT see the note (no share)
+        assert "results" in response_data
+        shared_note_ids = [
+            n["id"] for n in response_data["results"] if n["id"] == note_id
+        ]
+        assert len(shared_note_ids) == 0, "Diana should not see unshared note"
+        logger.info("Diana correctly cannot see unshared note")
+
+    finally:
+        # Cleanup
+        logger.info(f"Cleaning up note {note_id}")
+        await nc_client.notes.delete_note(note_id)
+
+
+@pytest.mark.asyncio
+async def test_notes_share_write_permissions(
+    nc_client, alice_mcp_client, charlie_mcp_client, bob_mcp_client
+):
+    """
+    Test that shared notes respect write permissions.
+
+    Scenario:
+    1. Admin creates a note as alice
+    2. Admin shares the note with charlie (edit permission)
+    3. Admin shares the note with bob (read-only)
+    4. Charlie can edit the note via MCP tools
+    5. Bob cannot edit the note
+    """
+    # Create a note as alice
+    note_title = "Alice's Shared Note - Write Test"
+    note_content = "This note is shared with Charlie for editing."
+    note_category = "SharedNotes"
+
+    logger.info("Creating note as alice...")
+    created_note = await nc_client.notes.create_note(
+        title=note_title, content=note_content, category=note_category
+    )
+    note_id = created_note.get("id")
+
+    try:
+        # TODO: Share the note with charlie (edit permission) and bob (read-only)
+        # Note: Nextcloud Notes sharing is folder-based
+
+        # Test: Charlie can append content to the note
+        logger.info("Charlie attempting to append content via MCP...")
+        result = await charlie_mcp_client.call_tool(
+            "nc_notes_append_content",
+            arguments={
+                "note_id": note_id,
+                "content": "\n\nCharlie added this content.",
+            },
+        )
+
+        # If sharing is properly configured, Charlie should succeed
+        # Without proper sharing setup, this will fail
+        logger.info(f"Charlie's append result: isError={result.isError}")
+        if not result.isError:
+            logger.info("Charlie successfully appended content (shares configured)")
+        else:
+            logger.warning("Charlie could not append (shares not yet configured)")
+
+        # Test: Bob attempts to append content (should fail)
+        logger.info("Bob attempting to append content via MCP...")
+        result = await bob_mcp_client.call_tool(
+            "nc_notes_append_content",
+            arguments={"note_id": note_id, "content": "\n\nBob tried to add this."},
+        )
+
+        # Bob should fail (read-only access)
+        logger.info(f"Bob's append result: isError={result.isError}")
+        if result.isError:
+            logger.info("Bob correctly denied write access")
+        else:
+            logger.warning("Bob unexpectedly succeeded (permissions issue?)")
+
+    finally:
+        # Cleanup
+        logger.info(f"Cleaning up note {note_id}")
+        await nc_client.notes.delete_note(note_id)
+
+
+@pytest.mark.asyncio
+async def test_user_isolation_notes(nc_client, alice_mcp_client, bob_mcp_client):
+    """
+    Test that users can only see their own notes when not shared.
+
+    Scenario:
+    1. Admin creates a note as alice (not shared)
+    2. Admin creates a note as bob (not shared)
+    3. Alice can only see her own note
+    4. Bob can only see his own note
+    """
+    # Create alice's note
+    logger.info("Creating alice's private note...")
+    alice_note = await nc_client.notes.create_note(
+        title="Alice's Private Note",
+        content="This is Alice's private content.",
+        category="AlicePrivate",
+    )
+    alice_note_id = alice_note.get("id")
+
+    # Create bob's note
+    logger.info("Creating bob's private note...")
+    bob_note = await nc_client.notes.create_note(
+        title="Bob's Private Note",
+        content="This is Bob's private content.",
+        category="BobPrivate",
+    )
+    bob_note_id = bob_note.get("id")
+
+    try:
+        # Test: Alice searches all notes
+        logger.info("Alice searching all notes via MCP...")
+        result = await alice_mcp_client.call_tool(
+            "nc_notes_search_notes", arguments={"query": ""}
+        )
+
+        assert result.isError is False
+        response_data = json.loads(result.content[0].text)
+        alice_notes = response_data.get("results", [])
+        alice_note_ids = [n["id"] for n in alice_notes]
+
+        logger.info(f"Alice can see {len(alice_notes)} notes")
+        # Alice should NOT see Bob's note
+        assert bob_note_id not in alice_note_ids, (
+            "Alice should not see Bob's private note"
+        )
+
+        # Test: Bob searches all notes
+        logger.info("Bob searching all notes via MCP...")
+        result = await bob_mcp_client.call_tool(
+            "nc_notes_search_notes", arguments={"query": ""}
+        )
+
+        assert result.isError is False
+        response_data = json.loads(result.content[0].text)
+        bob_notes = response_data.get("results", [])
+        bob_note_ids = [n["id"] for n in bob_notes]
+
+        logger.info(f"Bob can see {len(bob_notes)} notes")
+        # Bob should NOT see Alice's note
+        assert alice_note_id not in bob_note_ids, (
+            "Bob should not see Alice's private note"
+        )
+
+        logger.info("User isolation test passed: users can only see their own notes")
+
+    finally:
+        # Cleanup
+        logger.info("Cleaning up test notes...")
+        await nc_client.notes.delete_note(alice_note_id)
+        await nc_client.notes.delete_note(bob_note_id)
+
+
+@pytest.mark.asyncio
+async def test_oauth_mcp_clients_initialized(
+    alice_mcp_client, bob_mcp_client, charlie_mcp_client, diana_mcp_client
+):
+    """
+    Smoke test to verify all OAuth MCP clients are properly initialized.
+    """
+    logger.info("Testing alice_mcp_client initialization...")
+    result = await alice_mcp_client.call_tool(
+        "nc_notes_search_notes", arguments={"query": ""}
+    )
+    assert result.isError is False, f"Alice MCP client failed: {result.content}"
+    logger.info("Alice MCP client working")
+
+    logger.info("Testing bob_mcp_client initialization...")
+    result = await bob_mcp_client.call_tool(
+        "nc_notes_search_notes", arguments={"query": ""}
+    )
+    assert result.isError is False, f"Bob MCP client failed: {result.content}"
+    logger.info("Bob MCP client working")
+
+    logger.info("Testing charlie_mcp_client initialization...")
+    result = await charlie_mcp_client.call_tool(
+        "nc_notes_search_notes", arguments={"query": ""}
+    )
+    assert result.isError is False, f"Charlie MCP client failed: {result.content}"
+    logger.info("Charlie MCP client working")
+
+    logger.info("Testing diana_mcp_client initialization...")
+    result = await diana_mcp_client.call_tool(
+        "nc_notes_search_notes", arguments={"query": ""}
+    )
+    assert result.isError is False, f"Diana MCP client failed: {result.content}"
+    logger.info("Diana MCP client working")
+
+    logger.info("All OAuth MCP clients successfully initialized!")

tests/server/test_users_api.py

@@ -0,0 +1,108 @@
+import pytest
+from nextcloud_mcp_server.client import NextcloudClient
+
+
+@pytest.mark.asyncio
+async def test_create_and_delete_user(nc_client: NextcloudClient, test_user):
+    """Test creating a user and verifying deletion (cleanup by fixture)."""
+    user_config = test_user
+
+    # Create user
+    await nc_client.users.create_user(**user_config)
+
+    # Verify user exists
+    users = await nc_client.users.search_users(search=user_config["userid"])
+    assert user_config["userid"] in users
+
+    user_details = await nc_client.users.get_user_details(user_config["userid"])
+    assert user_details.id == user_config["userid"]
+    assert user_details.displayname == user_config["display_name"]
+    assert user_details.email == user_config["email"]
+
+    # Test deletion explicitly as part of test functionality
+    await nc_client.users.delete_user(user_config["userid"])
+
+    # Verify user is deleted
+    users = await nc_client.users.search_users(search=user_config["userid"])
+    assert user_config["userid"] not in users
+    # Note: Fixture cleanup will also try to delete but handle 404 gracefully
+
+
+@pytest.mark.asyncio
+async def test_update_user_field(nc_client: NextcloudClient, test_user):
+    """Test updating user fields."""
+    user_config = test_user
+
+    await nc_client.users.create_user(**user_config)
+
+    new_email = f"new.{user_config['email']}"
+    await nc_client.users.update_user_field(user_config["userid"], "email", new_email)
+
+    user_details = await nc_client.users.get_user_details(user_config["userid"])
+    assert user_details.email == new_email
+    # Fixture will handle cleanup
+
+
+@pytest.mark.asyncio
+async def test_user_groups(nc_client: NextcloudClient, test_user_in_group):
+    """Test adding and removing users from groups."""
+    user_config, groupid = test_user_in_group
+    userid = user_config["userid"]
+
+    # Verify user is in group
+    groups = await nc_client.users.get_user_groups(userid)
+    assert groupid in groups
+
+    # Remove user from group
+    await nc_client.users.remove_user_from_group(userid, groupid)
+    groups = await nc_client.users.get_user_groups(userid)
+    assert groupid not in groups
+    # Fixtures will handle cleanup
+
+
+@pytest.mark.asyncio
+async def test_user_subadmins(nc_client: NextcloudClient, test_user, test_group):
+    """Test promoting and demoting subadmins."""
+    user_config = test_user
+    groupid = test_group
+    userid = user_config["userid"]
+
+    await nc_client.users.create_user(**user_config)
+
+    # Promote to subadmin
+    await nc_client.users.promote_user_to_subadmin(userid, groupid)
+    subadmin_groups = await nc_client.users.get_user_subadmin_groups(userid)
+    assert groupid in subadmin_groups
+
+    # Demote from subadmin
+    await nc_client.users.demote_user_from_subadmin(userid, groupid)
+    subadmin_groups = await nc_client.users.get_user_subadmin_groups(userid)
+    assert groupid not in subadmin_groups
+    # Fixtures will handle cleanup
+
+
+@pytest.mark.asyncio
+async def test_disable_enable_user(nc_client: NextcloudClient, test_user):
+    """Test disabling and enabling users."""
+    user_config = test_user
+    userid = user_config["userid"]
+
+    await nc_client.users.create_user(**user_config)
+
+    # Disable user
+    await nc_client.users.disable_user(userid)
+    user_details = await nc_client.users.get_user_details(userid)
+    assert not user_details.enabled
+
+    # Enable user
+    await nc_client.users.enable_user(userid)
+    user_details = await nc_client.users.get_user_details(userid)
+    assert user_details.enabled
+    # Fixture will handle cleanup
+
+
+@pytest.mark.asyncio
+async def test_get_editable_user_fields(nc_client: NextcloudClient):
+    editable_fields = await nc_client.users.get_editable_user_fields()
+    assert "displayname" in editable_fields
+    assert "email" in editable_fields

tests/test_models.py

@@ -1,9 +1,9 @@
 """Unit tests for Pydantic models and serialization."""
 
-from datetime import datetime, timezone
 import json
 import logging
 import re
+from datetime import datetime, timezone
 
 from nextcloud_mcp_server.models.base import BaseResponse
 

user-api.rst

@@ -0,0 +1,674 @@
+=========================
+Instruction set for users
+=========================
+
+Add a new user
+--------------
+
+Create a new user on the Nextcloud server. Authentication is done by sending a
+basic HTTP authentication header.
+
+**Syntax: ocs/v1.php/cloud/users**
+
+* HTTP method: POST
+* POST argument: userid - string, the required username for the new user
+* POST argument: password - string, the password for the new user, leave empty to send welcome mail
+* POST argument: displayName - string, the display name for the new user
+* POST argument: email - string, the email for the new user, required if password empty
+* POST argument: groups - array, the groups for the new user
+* POST argument: subadmin - array, the groups in which the new user is subadmin
+* POST argument: quota - string, quota for the new user
+* POST argument: language - string, language for the new user
+
+Status codes:
+
+* 101 - invalid argument
+* 102 - user already exists
+* 103 - cannot create sub-admins for admin group
+* 104 - group does not exist
+* 105 - insufficient privileges for group
+* 106 - no group specified (required for sub-admins)
+* 107 - hint exceptions
+* 108 - an email address is required, to send a password link to the user.
+* 109 - sub-admin group does not exist
+* 110 - required email address was not provided
+* 111 - could not create non-existing user ID
+
+Example
+^^^^^^^
+::
+
+  $ curl -X POST http://admin:secret@example.com/ocs/v1.php/cloud/users -d userid="Frank" -d password="frankspassword" -H "OCS-APIRequest: true"
+
+* Creates the user ``Frank`` with password ``frankspassword``
+* optionally groups can be specified by one or more ``groups[]`` query parameters:
+  ``URL -d groups[]="admin" -D groups[]="Team1"``
+
+XML output
+^^^^^^^^^^
+
+.. code-block:: xml
+
+ <?xml version="1.0"?>
+ <ocs>
+  <meta>
+   <status>ok</status>
+   <statuscode>100</statuscode>
+   <message/>
+  </meta>
+  <data/>
+ </ocs>
+
+Search/get users
+----------------
+
+Retrieves a list of users from the Nextcloud server. Authentication is done by
+sending a Basic HTTP Authorization header.
+
+**Syntax: ocs/v1.php/cloud/users**
+
+* HTTP method: GET
+* url arguments: search - string, optional search string
+* url arguments: limit - int, optional limit value
+* url arguments: offset - int, optional offset value
+
+Status codes:
+
+* 100 - successful
+
+Example
+^^^^^^^
+::
+
+  $ curl -X GET http://admin:secret@example.com/ocs/v1.php/cloud/users?search=Frank -H "OCS-APIRequest: true"
+
+* Returns list of users matching the search string.
+
+XML output
+^^^^^^^^^^
+
+.. code-block:: xml
+
+  <?xml version="1.0"?>
+  <ocs>
+    <meta>
+      <statuscode>100</statuscode>
+      <status>ok</status>
+    </meta>
+    <data>
+      <users>
+        <element>Frank</element>
+       </users>
+    </data>
+  </ocs>
+
+Get data of a single user
+-------------------------
+
+Retrieves information about a single user. Authentication is done by sending a
+Basic HTTP Authorization header.
+
+**Syntax: ocs/v1.php/cloud/users/{userid}**
+
+* HTTP method: GET
+
+Status codes:
+
+* 100 - successful
+
+Example
+^^^^^^^
+
+::
+
+  $ curl -X GET http://admin:secret@example.com/ocs/v1.php/cloud/users/Frank -H "OCS-APIRequest: true"
+
+* Returns information on the user ``Frank``
+
+XML output
+^^^^^^^^^^
+
+.. code-block:: xml
+
+  <?xml version="1.0"?>
+  <ocs>
+    <meta>
+      <statuscode>100</statuscode>
+      <status>ok</status>
+    </meta>
+    <data>
+      <enabled>true</enabled>
+      <id>Frank</id>
+      <quota>0</quota>
+      <email>frank@example.org</email>
+      <displayname>Frank K.</displayname>
+      <display-name>Frank K.</display-name>
+      <phone>0123 / 456 789</phone>
+      <address>Foobar 12, 12345 Town</address>
+      <website>https://nextcloud.com</website>
+      <twitter>Nextcloud</twitter>
+      <groups>
+       <element>group1</element>
+       <element>group2</element>
+      </groups>
+    </data>
+  </ocs>
+
+Edit data of a single user
+--------------------------
+
+Edits attributes related to a user. Users are able to edit email, displayname
+and password; admins can also edit the quota value. Further restrictions may apply,
+check the `List of editable data fields`_ endpoint. Authentication
+is done by sending a Basic HTTP Authorization header.
+
+**Syntax: ocs/v1.php/cloud/users/{userid}**
+
+* HTTP method: PUT
+* PUT argument: key, the field to edit:
+
+  + email
+  + quota
+  + displayname
+  + display (**deprecated** use `displayname` instead)
+  + phone
+  + address
+  + website
+  + twitter
+  + password
+
+* PUT argument: value, the new value for the field
+
+Status codes:
+
+* 101 - invalid argument
+* 107 - password policy (hint exception)
+* 112 - Setting the password is not supported by the users backend
+* 113 - editing field not allowed / field doesn’t exist
+
+Examples
+^^^^^^^^
+
+::
+
+  $ curl -X PUT http://admin:secret@example.com/ocs/v1.php/cloud/users/Frank -d key="email" -d value="franksnewemail@example.org" -H "OCS-APIRequest: true"
+
+* Updates the email address for the user ``Frank``
+
+::
+
+  $ curl -X PUT http://admin:secret@example.com/ocs/v1.php/cloud/users/Frank -d key="quota" -d value="100MB" -H "OCS-APIRequest: true"
+
+* Updates the quota for the user ``Frank``
+
+XML output
+^^^^^^^^^^
+
+.. code-block:: xml
+
+  <?xml version="1.0"?>
+  <ocs>
+    <meta>
+      <statuscode>100</statuscode>
+      <status>ok</status>
+    </meta>
+    <data/>
+  </ocs>
+
+.. _editable_field_list:
+
+List of editable data fields
+----------------------------
+
+Edits attributes related to a user. Users are able to edit email, displayname
+and password; admins can also edit the quota value. Authentication is done by
+sending a Basic HTTP Authorization header.
+
+**Syntax: ocs/v1.php/cloud/user/fields**
+
+* HTTP method: GET
+
+Status codes:
+
+* 100 - successful
+
+Examples
+^^^^^^^^
+
+::
+
+  $ curl -X GET http://admin:secret@example.com/ocs/v1.php/cloud/user/fields -H "OCS-APIRequest: true"
+
+* Gets the list of fields
+
+XML output
+^^^^^^^^^^
+
+.. code-block:: xml
+
+  <?xml version="1.0"?>
+  <ocs>
+   <meta>
+    <status>ok</status>
+    <statuscode>100</statuscode>
+    <message>OK</message>
+   </meta>
+   <data>
+    <element>displayname</element>
+    <element>email</element>
+    <element>phone</element>
+    <element>address</element>
+    <element>website</element>
+    <element>twitter</element>
+   </data>
+  </ocs>
+
+
+Disable a user
+--------------
+
+Disables a user on the Nextcloud server so that the user cannot login anymore.
+Authentication is done by sending a Basic HTTP Authorization header.
+
+**Syntax: ocs/v1.php/cloud/users/{userid}/disable**
+
+* HTTP method: PUT
+
+Statuscodes:
+
+* 100 - successful
+* 101 - failure
+
+Example
+^^^^^^^
+
+::
+
+  $ curl -X PUT http://admin:secret@example.com/ocs/v1.php/cloud/users/Frank/disable -H "OCS-APIRequest: true"
+
+* Disables the user ``Frank``
+
+XML output
+^^^^^^^^^^
+
+.. code-block:: xml
+
+  <?xml version="1.0"?>
+  <ocs>
+    <meta>
+      <status>ok</status>
+      <statuscode>100</statuscode>
+      <message/>
+    </meta>
+    <data/>
+  </ocs>
+
+Enable a user
+-------------
+
+Enables a user on the Nextcloud server so that the user can login again.
+Authentication is done by sending a Basic HTTP Authorization header.
+
+**Syntax: ocs/v1.php/cloud/users/{userid}/enable**
+
+* HTTP method: PUT
+
+Statuscodes:
+
+* 100 - successful
+* 101 - failure
+
+Example
+^^^^^^^
+
+::
+
+  $ curl -X PUT http://admin:secret@example.com/ocs/v1.php/cloud/users/Frank/enable -H "OCS-APIRequest: true"
+
+* Enables the user ``Frank``
+
+XML output
+^^^^^^^^^^
+
+.. code-block:: xml
+
+  <?xml version="1.0"?>
+  <ocs>
+    <meta>
+      <status>ok</status>
+      <statuscode>100</statuscode>
+      <message/>
+    </meta>
+    <data/>
+  </ocs>
+
+Delete a user
+-------------
+
+Deletes a user from the Nextcloud server. Authentication is done by sending a
+Basic HTTP Authorization header.
+
+**Syntax: ocs/v1.php/cloud/users/{userid}**
+
+* HTTP method: DELETE
+
+Statuscodes:
+
+* 100 - successful
+* 101 - failure
+
+Example
+^^^^^^^
+
+::
+
+  $ curl -X DELETE http://admin:secret@example.com/ocs/v1.php/cloud/users/Frank -H "OCS-APIRequest: true"
+
+* Deletes the user ``Frank``
+
+XML output
+^^^^^^^^^^
+
+.. code-block:: xml
+
+  <?xml version="1.0"?>
+  <ocs>
+    <meta>
+      <statuscode>100</statuscode>
+      <status>ok</status>
+    </meta>
+    <data/>
+  </ocs>
+
+Get user's groups
+-----------------
+
+Retrieves a list of groups the specified user is a member of. Authentication is
+done by sending a Basic HTTP Authorization header.
+
+**Syntax: ocs/v1.php/cloud/users/{userid}/groups**
+
+* HTTP method: GET
+
+Status codes:
+
+* 100 - successful
+
+Example
+^^^^^^^
+
+::
+
+  $ curl -X GET http://admin:secret@example.com/ocs/v1.php/cloud/users/Frank/groups -H "OCS-APIRequest: true"
+
+* Retrieves a list of groups of which ``Frank`` is a member
+
+XML output
+^^^^^^^^^^
+
+.. code-block:: xml
+
+  <?xml version="1.0"?>
+  <ocs>
+    <meta>
+      <statuscode>100</statuscode>
+      <status>ok</status>
+    </meta>
+    <data>
+      <groups>
+        <element>admin</element>
+        <element>group1</element>
+      </groups>
+    </data>
+  </ocs>
+
+Add user to group
+-----------------
+
+Adds the specified user to the specified group. Authentication is done by
+sending a Basic HTTP Authorization header.
+
+**Syntax: ocs/v1.php/cloud/users/{userid}/groups**
+
+* HTTP method: POST
+* POST argument: groupid, string - the group to add the user to
+
+Status codes:
+
+* 100 - successful
+* 101 - no group specified
+* 102 - group does not exist
+* 103 - user does not exist
+* 104 - insufficient privileges
+* 105 - failed to add user to group
+
+Example
+^^^^^^^
+
+::
+
+  $ curl -X POST http://admin:secret@example.com/ocs/v1.php/cloud/users/Frank/groups -d groupid="newgroup" -H "OCS-APIRequest: true"
+
+* Adds the user ``Frank`` to the group ``newgroup``
+
+XML output
+^^^^^^^^^^
+
+.. code-block:: xml
+
+  <?xml version="1.0"?>
+  <ocs>
+    <meta>
+      <statuscode>100</statuscode>
+      <status>ok</status>
+    </meta>
+    <data/>
+  </ocs>
+
+Remove user from group
+----------------------
+
+Removes the specified user from the specified group. Authentication is done by
+sending a Basic HTTP Authorization header.
+
+**Syntax: ocs/v1.php/cloud/users/{userid}/groups**
+
+* HTTP method: DELETE
+* DELETE argument: groupid, string - the group to remove the user from
+
+Status codes:
+
+* 100 - successful
+* 101 - no group specified
+* 102 - group does not exist
+* 103 - user does not exist
+* 104 - insufficient privileges
+* 105 - failed to remove user from group
+
+Example
+^^^^^^^
+
+::
+
+  $ curl -X DELETE http://admin:secret@example.com/ocs/v1.php/cloud/users/Frank/groups -d groupid="newgroup" -H "OCS-APIRequest: true"
+
+* Removes the user ``Frank`` from the group ``newgroup``
+
+XML output
+^^^^^^^^^^
+
+.. code-block:: xml
+
+  <?xml version="1.0"?>
+  <ocs>
+    <meta>
+      <statuscode>100</statuscode>
+      <status>ok</status>
+    </meta>
+    <data/>
+  </ocs>
+
+Promote user to subadmin
+------------------------
+
+Makes a user the subadmin of a group. Authentication is done by sending a Basic
+HTTP Authorization header.
+
+**Syntax: ocs/v1.php/cloud/users/{userid}/subadmins**
+
+* HTTP method: POST
+* POST argument: groupid, string - the group of which to make the user a
+  subadmin
+
+Status codes:
+
+* 100 - successful
+* 101 - user does not exist
+* 102 - group does not exist
+* 103 - unknown failure
+
+Example
+^^^^^^^
+
+::
+
+  $ curl -X POST https://admin:secret@example.com/ocs/v1.php/cloud/users/Frank/subadmins -d groupid="group" -H "OCS-APIRequest: true"
+
+* Makes the user ``Frank`` a subadmin of the ``group`` group
+
+XML output
+^^^^^^^^^^
+
+.. code-block:: xml
+
+  <?xml version="1.0"?>
+  <ocs>
+    <meta>
+      <statuscode>100</statuscode>
+      <status>ok</status>
+    </meta>
+    <data/>
+  </ocs>
+
+Demote user from subadmin
+-------------------------
+
+Removes the subadmin rights for the user specified from the group specified.
+Authentication is done by sending a Basic HTTP Authorization header.
+
+**Syntax: ocs/v1.php/cloud/users/{userid}/subadmins**
+
+* HTTP method: DELETE
+* DELETE argument: groupid, string - the group from which to remove the user's
+  subadmin rights
+
+Status codes:
+
+* 100 - successful
+* 101 - user does not exist
+* 102 - user is not a subadmin of the group / group does not exist
+* 103 - unknown failure
+
+Example
+^^^^^^^
+
+::
+
+  $ curl -X DELETE https://admin:secret@example.com/ocs/v1.php/cloud/users/Frank/subadmins -d groupid="oldgroup" -H "OCS-APIRequest: true"
+
+* Removes ``Frank's`` subadmin rights from the ``oldgroup`` group
+
+XML output
+^^^^^^^^^^
+
+.. code-block:: xml
+
+  <?xml version="1.0"?>
+  <ocs>
+    <meta>
+      <statuscode>100</statuscode>
+      <status>ok</status>
+    </meta>
+    <data/>
+  </ocs>
+
+Get user's subadmin groups
+--------------------------
+
+Returns the groups in which the user is a subadmin. Authentication is done by
+sending a Basic HTTP Authorization header.
+
+**Syntax: ocs/v1.php/cloud/users/{userid}/subadmins**
+
+* HTTP method: GET
+
+Status codes:
+
+* 100 - successful
+* 101 - user does not exist
+* 102 - unknown failure
+
+Example
+^^^^^^^
+
+::
+
+  $ curl -X GET https://admin:secret@example.com/ocs/v1.php/cloud/users/Frank/subadmins -H "OCS-APIRequest: true"
+
+* Returns the groups of which ``Frank`` is a subadmin
+
+XML output
+^^^^^^^^^^
+
+.. code-block:: xml
+
+  <?xml version="1.0"?>
+  <ocs>
+    <meta>
+        <status>ok</status>
+        <statuscode>100</statuscode>
+      <message/>
+    </meta>
+    <data>
+      <element>testgroup</element>
+    </data>
+  </ocs>
+
+Resend the welcome email
+------------------------
+
+The request to this endpoint triggers the welcome email for this user again.
+
+**Syntax: ocs/v1.php/cloud/users/{userid}/welcome**
+
+* HTTP method: POST
+
+Status codes:
+
+* 100 - successful
+* 101 - email address not available
+* 102 - sending email failed
+
+Example
+^^^^^^^
+
+::
+
+  $ curl -X POST https://admin:secret@example.com/ocs/v1.php/cloud/users/Frank/welcome -H "OCS-APIRequest: true"
+
+* Sends the welcome email to ``Frank``
+
+XML output
+^^^^^^^^^^
+
+.. code-block:: xml
+
+  <?xml version="1.0"?>
+  <ocs>
+    <meta>
+        <status>ok</status>
+        <statuscode>100</statuscode>
+      <message/>
+    </meta>
+    <data/>
+  </ocs>