brandon/nextcloud-mcp-server
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge branch 'master' into feature/introduce_files_parsing_with_unstructured_service_for_webdav_files_retrieval

Browse Source
This commit is contained in:
yuisheaven
2025-10-21 20:37:00 +02:00
committed by GitHub
parent 3ff6346c03 f4f9548681
commit 64649c902d
111 changed files with 20581 additions and 1795 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.github/workflows/bump-version.yml
+1 -1
View File
@@ -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/release.yml
+33
View File
@@ -0,0 +1,33 @@
name: Release
on:
push:
tags:
- v*
jobs:
pypi:
name: Publish to PyPI
runs-on: ubuntu-latest
# Environment and permissions trusted publishing.
environment:
# Create this environment in the GitHub repository under Settings -> Environments
name: pypi
permissions:
id-token: write
contents: read
steps:
- name: Checkout
uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5
- name: Install uv
uses: astral-sh/setup-uv@2ddd2b9cb38ad8efd50337e8ab201519a34c9f24 # v7
- name: Install Python 3.11
run: uv python install 3.11
- name: Build
run: uv build
- name: Smoke test (wheel)
run: uv run --isolated --no-project --with dist/*.whl nextcloud-mcp-server --help
- name: Smoke test (source distribution)
run: uv run --isolated --no-project --with dist/*.tar.gz nextcloud-mcp-server --help
- name: Publish
run: uv publish
.github/workflows/test.yml
+10 -4
View File
@@ -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@d0cc045d04ccac9d8b7881df0226f9e82c39688e # v6.8.0
uses: astral-sh/setup-uv@2ddd2b9cb38ad8efd50337e8ab201519a34c9f24 # v7.1.1
- 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@b716db5b717cb9b81e391fe638e5aceaa2299e43 # v2.4.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@d0cc045d04ccac9d8b7881df0226f9e82c39688e # v6.8.0
uses: astral-sh/setup-uv@2ddd2b9cb38ad8efd50337e8ab201519a34c9f24 # v7.1.1
- name: Install Playwright dependencies
run: |
uv run playwright install chromium --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 --log-level=INFO
.gitignore
+3
View File
@@ -4,3 +4,6 @@ __pycache__/
*.env
.env.local
.env.*.local
# Generated by pytest used to login users
.nextcloud_oauth_*.json
CHANGELOG.md
+92
View File
@@ -1,3 +1,95 @@
## v0.17.1 (2025-10-20)
### Fix
- **caldav**: Fix caldav search() due to missing todos
## v0.17.0 (2025-10-19)
### Feat
- **caldav**: Add support for tasks
### Fix
- **caldav**: Check that calendar exists after creation to avoid race condition
- **caldav**: Properly parse datetimes as vDDDTypes
### Refactor
- Migrate from internal CalendarClient to caldav library
## v0.16.0 (2025-10-19)
### Feat
- **webdav**: Add search and list favorite response tools
### Perf
- **notes**: Improve notes search performance using async iterators
## v0.15.2 (2025-10-17)
### Refactor
- Unify logging & remove factory deployment
## v0.15.1 (2025-10-17)
### Fix
- Increase HTTP client timeout to 30s
- Handle RequestError in mcp tools
## v0.15.0 (2025-10-17)
### Feat
- **cookbook**: Add full Cookbook app support with 13 tools and 2 resources
## v0.14.3 (2025-10-17)
### Fix
- **deps**: update dependency mcp to >=1.18,<1.19
## v0.14.2 (2025-10-16)
### Fix
- **deps**: update dependency pillow to v12
## v0.14.1 (2025-10-15)
### Fix
- **oauth**: Remove the option to force_register new clients
## v0.14.0 (2025-10-15)
### Feat
- Add Groups API client
- add sharing API client and server tools
- **users**: Initialize user API client
### Fix
- Update user/groups API to OCS v2
## 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
CLAUDE.md
+138 -8
View File
@@ -21,6 +21,53 @@ uv run pytest -m "not integration"
! Hint: If the tests are failing due to missing environment variables, then usually the correct .env has not been created or not correctly configured yet.
### Load Testing
```bash
# Run benchmark with default settings (10 workers, 30 seconds)
uv run python -m tests.load.benchmark
# Quick test with custom concurrency and duration
uv run python -m tests.load.benchmark --concurrency 20 --duration 60
# Extended load test (50 workers for 5 minutes)
uv run python -m tests.load.benchmark -c 50 -d 300
# Export results to JSON for analysis
uv run python -m tests.load.benchmark -c 20 -d 60 --output results.json
# Test OAuth server on port 8001
uv run python -m tests.load.benchmark --url http://127.0.0.1:8001/mcp
# Verbose mode with detailed logging
uv run python -m tests.load.benchmark -c 10 -d 30 --verbose
```
**Load Testing Features:**
- **Mixed workload** simulating realistic MCP usage (40% reads, 20% writes, 15% search, 25% other operations)
- **Real-time progress** bar with live RPS and error counts
- **Detailed metrics**:
- Throughput (requests/second)
- Latency percentiles (p50, p90, p95, p99)
- Per-operation breakdown
- Error rates and types
- **Automatic cleanup** of test data
- **JSON export** for CI/CD integration
- **Server health checks** before starting
**Understanding Results:**
- **Requests/Second (RPS)**: Higher is better. Expected baseline: 50-200 RPS for mixed workload
- **Latency**:
- p50 (median): Should be <100ms for most operations
- p95: Should be <500ms
- p99: Should be <1000ms
- **Error Rate**: Should be <1% under normal load
**Common Bottlenecks:**
1. Nextcloud backend API response times (most common)
2. Database connection limits
3. HTTP client connection pooling
4. Network I/O between containers
### Code Quality
```bash
# Format and lint code
@@ -40,13 +87,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
@@ -83,7 +138,17 @@ Each Nextcloud app has a corresponding server module that:
### Supported Nextcloud Apps
- **Notes** - Full CRUD operations and search
- **Calendar** - CalDAV integration with events, recurring events, attendees
- **Calendar** - CalDAV integration with events, recurring events, attendees, and **tasks (VTODO)**
- **Calendar Operations**: List, create, delete calendars
- **Event Operations**: Full CRUD, recurring events, attendees, reminders, bulk operations
- **Task Operations (VTODO)**: Full CRUD for CalDAV tasks with:
- Status tracking (NEEDS-ACTION, IN-PROCESS, COMPLETED, CANCELLED)
- Priority levels (0-9, 1=highest, 9=lowest)
- Due dates, start dates, completion tracking
- Percent complete (0-100%)
- Categories and filtering
- Search across all calendars
- **Note**: Calendar implementation uses caldav library's AsyncDavClient
- **Contacts** - CardDAV integration with address book operations
- **Tables** - Row-level operations on Nextcloud Tables
- **WebDAV** - Complete file system access
@@ -96,29 +161,94 @@ Each Nextcloud app has a corresponding server module that:
4. **Context injection** - MCP context provides access to the authenticated client instance
5. **Modular design** - Each Nextcloud app is isolated in its own client/server pair
### MCP Response Patterns
**CRITICAL: Never return raw `List[Dict]` from MCP tools - always wrap in Pydantic response models**
FastMCP serialization issue: raw lists get mangled into dicts with numeric string keys.
**Pattern:**
1. Client methods return `List[Dict]` (raw data)
2. MCP tools convert to Pydantic models and wrap in response object
3. Response models inherit from `BaseResponse`, include `results` field + metadata
**Reference implementations:**
- `SearchNotesResponse` in `nextcloud_mcp_server/models/notes.py:80`
- `SearchFilesResponse` in `nextcloud_mcp_server/models/webdav.py:113`
- Tool examples: `nextcloud_mcp_server/server/{notes,webdav}.py`
**Testing:** Extract `data["results"]` from MCP responses, not `data` directly.
### Testing Structure
- **Integration tests** in `tests/integration/` - Test real Nextcloud API interactions
- **Integration tests** in `tests/client/` and `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
- `temporary_contact` - Creates and cleans up test contacts
- **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 Notes changes: `uv run pytest tests/server/test_mcp.py -k "notes" -v`
- For specific API changes: `uv run pytest tests/client/notes/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 use **automated Playwright browser automation** to complete the OAuth flow programmatically.
**OAuth Testing Setup:**
- **Main fixtures**: `nc_oauth_client`, `nc_mcp_oauth_client` - Use Playwright automation
- **Shared OAuth Client**: All test users authenticate using a single OAuth client
- Stored in `.nextcloud_oauth_shared_test_client.json`
- Matches production MCP server behavior
- Each user gets their own unique access token
- Implementation: `shared_oauth_client_credentials` fixture in `tests/conftest.py`
- **Available fixtures**: `playwright_oauth_token`, `nc_oauth_client`, `nc_mcp_oauth_client`
- **Multi-user fixtures**: `alice_oauth_token`, `bob_oauth_token`, `charlie_oauth_token`, `diana_oauth_token`
- **Requirements**: `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 Commands:**
```bash
# Run all OAuth tests with Playwright automation using Firefox
uv run pytest tests/server/test_oauth*.py --browser firefox -v
# Run specific 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
```
**Test Environment:**
- **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`
- OAuth client credentials cached in `.nextcloud_oauth_shared_test_client.json`
**CI/CD Notes:**
- Playwright tests run in CI/CD environments
- Use Firefox browser in CI: `--browser firefox` (Chromium may have issues with localhost redirects)
### Configuration Files
- **`pyproject.toml`** - Python project configuration using uv for dependency management
Dockerfile
+6 -1
View File
@@ -1,4 +1,7 @@
FROM ghcr.io/astral-sh/uv:0.8.22-python3.11-alpine@sha256:a8d5f7079a3223380ec060fefe48afe45b4c4622d631ce0e495593ac9a38f546
FROM ghcr.io/astral-sh/uv:0.9.4-python3.11-alpine@sha256:1a51c7710eaf839fa3365329ad993b48d17ddd9ab0f0672efaa9b09f407ebf44
# Install git (required for caldav dependency from git)
RUN apk add --no-cache git
WORKDIR /app
@@ -6,4 +9,6 @@ COPY . .
RUN uv sync --locked --no-dev
ENV PYTHONUNBUFFERED=1
ENTRYPOINT ["/app/.venv/bin/nextcloud-mcp-server", "--host", "0.0.0.0"]
README.md
+227 -202
View File
@@ -2,258 +2,283 @@
[![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.**
## Features
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.
The server provides integration with multiple Nextcloud apps, enabling LLMs to interact with your Nextcloud data through a rich set of tools and resources.
> [!NOTE]
> **Nextcloud has two ways to enable AI access:** Nextcloud provides [Context Agent](https://github.com/nextcloud/context_agent), an AI agent backend that powers the [Assistant](https://github.com/nextcloud/assistant) app and allows AI to interact with Nextcloud apps like Calendar, Talk, and Contacts. Context Agent runs as an ExApp inside Nextcloud and also _[exposes an MCP server](https://docs.nextcloud.com/server/stable/admin_manual/ai/app_context_agent.html#using-nextcloud-mcp-server)_ for external MCP clients.
>
> This project (Nextcloud MCP Server) is a **dedicated standalone MCP server** designed specifically for external MCP clients like Claude Code and IDEs, with deep CRUD operations and OAuth support. It does not require any additional AI-features to be enabled in Nextcloud beyond the apps that you intend to interact with.
## Supported Nextcloud Apps
### High-level Comparison: Nextcloud MCP Server vs. Nextcloud AI Stack
| 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 |
| Aspect | **Nextcloud MCP Server**<br/>(This Project) | **Nextcloud AI Stack**<br/>(Assistant + Context Agent) |
|--------|---------------------------------------------|--------------------------------------------------------|
| **Purpose** | External MCP client access to Nextcloud | AI assistance within Nextcloud UI |
| **Deployment** | Standalone (Docker, VM, K8s) | Inside Nextcloud (ExApp via AppAPI) |
| **Primary Users** | Claude Code, IDEs, external developers | Nextcloud end users via Assistant app |
| **Authentication** | OAuth2/OIDC or Basic Auth | Session-based (integrated) |
| **Notes Support** | ✅ Full CRUD + search (7 tools) | ❌ Not implemented |
| **Calendar** | ✅ Full CalDAV + tasks (20+ tools) | ✅ Events, free/busy, tasks (4 tools) |
| **Contacts** | ✅ Full CardDAV (8 tools) | ✅ Find person, current user (2 tools) |
| **Files (WebDAV)** | ✅ Full filesystem access (12 tools) | ✅ Read, folder tree, sharing (3 tools) |
| **Deck** | ✅ Full project management (15 tools) | ✅ Basic board/card ops (2 tools) |
| **Tables** | ✅ Row operations (5 tools) | ❌ Not implemented |
| **Cookbook** | ✅ Full recipe management (13 tools) | ❌ Not implemented |
| **Talk** | ❌ Not implemented | ✅ Messages, conversations (4 tools) |
| **Mail** | ❌ Not implemented | ✅ Send email (2 tools) |
| **AI Features** | ❌ Not implemented | ✅ Image gen, transcription, doc gen (4 tools) |
| **Web/Maps** | ❌ Not implemented | ✅ Search, weather, transit (5 tools) |
| **MCP Resources** | ✅ Structured data URIs | ❌ Not supported |
| **External MCP** | ❌ Pure server | ✅ Consumes external MCP servers |
| **Safety Model** | Client-controlled | Built-in safe/dangerous distinction |
| **Best For** | • Deep CRUD operations<br/>• External integrations<br/>• OAuth security<br/>• IDE/editor integration | • AI-driven actions in Nextcloud UI<br/>• Multi-service orchestration<br/>• User task automation<br/>• MCP aggregation hub |
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.
See our [detailed comparison](docs/comparison-context-agent.md) for architecture diagrams, workflow examples, and guidance on when to use each approach.
## Available Tools & Resources
Want to see another Nextcloud app supported? [Open an issue](https://github.com/cbcoutinho/nextcloud-mcp-server/issues) or contribute a pull request!
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.
### Authentication
### 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 |
| Mode | Security | Best For |
|------|----------|----------|
| **OAuth2/OIDC** ⚠️ **Experimental** | 🔒 High | Testing, evaluation (requires patch for app-specific APIs) |
| **Basic Auth** ✅ | Lower | Development, testing, production |
> [!IMPORTANT]
> **OAuth is experimental** and requires a manual patch to the `user_oidc` app for full functionality:
> - **Required patch**: `user_oidc` app needs modifications for Bearer token support ([issue #1221](https://github.com/nextcloud/user_oidc/issues/1221))
> - **Impact**: Without the patch, most app-specific APIs (Notes, Calendar, Contacts, Deck, etc.) will fail with 401 errors
> - **What works without patches**: OAuth flow, PKCE support (with `oidc` v1.10.0+), OCS APIs
> - **Production use**: Wait for upstream patch to be merged into official releases
>
> See [OAuth Upstream Status](docs/oauth-upstream-status.md) for detailed information on required patches and workarounds.
### Tools vs Resources
OAuth2/OIDC provides secure, per-user authentication with access tokens. See [Authentication Guide](docs/authentication.md) for details.
**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`
## Quick Start
**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`
### 1. Install
```bash
# Clone the repository
git clone https://github.com/cbcoutinho/nextcloud-mcp-server.git
cd nextcloud-mcp-server
## Installation
# Install with uv (recommended)
uv sync
### Prerequisites
# Or using Docker
docker pull ghcr.io/cbcoutinho/nextcloud-mcp-server:latest
```
* Python 3.11+
* Access to a Nextcloud instance
See [Installation Guide](docs/installation.md) for detailed instructions.
### Local Installation
### 2. Configure
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
```
Create a `.env` file:
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 Basic Auth (recommended for most users):**
```dotenv
# .env
NEXTCLOUD_HOST=https://your.nextcloud.instance.com
NEXTCLOUD_USERNAME=your_nextcloud_username
NEXTCLOUD_PASSWORD=your_nextcloud_app_password_or_login_password
NEXTCLOUD_USERNAME=your_username
NEXTCLOUD_PASSWORD=your_app_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 OAuth (experimental - requires patches):**
```dotenv
NEXTCLOUD_HOST=https://your.nextcloud.instance.com
```
### 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
**Basic Auth Setup (recommended):**
1. Create an app password in Nextcloud (Settings → Security → Devices & sessions)
2. Add credentials to `.env` file
3. Start the server
**OAuth Setup (experimental):**
1. Install Nextcloud OIDC apps (`oidc` v1.10.0+ + `user_oidc`)
2. **Apply required patch** to `user_oidc` app for Bearer token support (see [OAuth Upstream Status](docs/oauth-upstream-status.md))
3. Enable dynamic client registration or create an OIDC client with id & secret
4. Configure Bearer token validation in `user_oidc`
5. Start the server
See [OAuth Quick Start](docs/quickstart-oauth.md) for 5-minute setup or [OAuth Setup Guide](docs/oauth-setup.md) for detailed instructions.
### 4. Run the Server
```bash
# 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 with Basic Auth (default)
uv run nextcloud-mcp-server
# Enable only specific Nextcloud app APIs
uv run python -m nextcloud_mcp_server.app --enable-app notes --enable-app calendar
# Or start with OAuth (experimental - requires patches)
uv run nextcloud-mcp-server --oauth
# 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
```
#### 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
### Architecture
- **[Comparison with Context Agent](docs/comparison-context-agent.md)** - How this MCP server differs from Nextcloud's Context Agent
### OAuth Documentation (Experimental)
- **[OAuth Quick Start](docs/quickstart-oauth.md)** - 5-minute setup guide
- **[OAuth Setup Guide](docs/oauth-setup.md)** - Detailed setup instructions
- **[OAuth Architecture](docs/oauth-architecture.md)** - How OAuth works
- **[OAuth Troubleshooting](docs/oauth-troubleshooting.md)** - OAuth-specific issues
- **[Upstream Status](docs/oauth-upstream-status.md)** - **Required patches and PRs** ⚠️
### Reference
- **[Troubleshooting](docs/troubleshooting.md)** - Common issues and solutions
### App-Specific Documentation
- [Notes API](docs/notes.md)
- [Calendar (CalDAV)](docs/calendar.md)
- [Contacts (CardDAV)](docs/contacts.md)
- [Cookbook](docs/cookbook.md)
- [Deck](docs/deck.md)
- [Tables](docs/table.md)
- [WebDAV](docs/webdav.md)
## MCP Tools & Resources
The server exposes Nextcloud functionality through MCP tools (for actions) and resources (for data browsing).
### Tools
Tools enable AI assistants to perform actions:
- `nc_notes_create_note` - Create a new note
- `nc_cookbook_import_recipe` - Import recipes from URLs with schema.org metadata
- `deck_create_card` - Create a Deck card
- `nc_calendar_create_event` - Create a calendar event
- `nc_contacts_create_contact` - Create a contact
- And many more...
### Resources
Resources provide read-only access to Nextcloud data:
- `nc://capabilities` - Server capabilities
- `cookbook://version` - Cookbook app version info
- `nc://Deck/boards/{board_id}` - Deck board data
- `notes://settings` - Notes app settings
- And more...
Run `uv run nextcloud-mcp-server --help` to see all available options.
## Examples
### Create a Note
```
AI: "Create a note called 'Meeting Notes' with today's agenda"
→ Uses nc_notes_create_note tool
```
### Manage Recipes
```
AI: "Import the recipe from this URL: https://www.example.com/recipe/chocolate-cake"
→ Uses nc_cookbook_import_recipe tool to extract schema.org metadata
```
### 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 (experimental - requires upstream patches)
- Basic Auth with app-specific passwords (recommended)
- 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 [LICENSE](./LICENSE) for details.
## 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)
## License
## References
This project is licensed under the AGPL-3.0 License. See the [LICENSE](./LICENSE) file 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)
- [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
+69
View File
@@ -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/install-calendar-app.sh
+6 -2
View File
@@ -1,19 +1,23 @@
#!/bin/bash
set -e # Exit on any error
set -euox pipefail
echo "Installing and configuring Calendar app..."
# Enable calendar app
php /var/www/html/occ app:enable calendar
php /var/www/html/occ app:enable --force tasks # Not currently supported on 32
# Wait for calendar app to be fully initialized
echo "Waiting for calendar app to initialize..."
sleep 5
# Increase limits on calendar creation for integration tests (100 in 60s)
# Disable rate limits on calendar creation for integration tests
# Set to -1 to completely disable rate limiting
# Reference: https://docs.nextcloud.com/server/stable/admin_manual/groupware/calendar.html#rate-limits
php occ config:app:set dav rateLimitCalendarCreation --type=integer --value=100
php occ config:app:set dav rateLimitPeriodCalendarCreation --type=integer --value=60
php occ config:app:set dav maximumCalendarsSubscriptions --type=integer --value=-1
# Ensure maintenance mode is off before calendar operations
php /var/www/html/occ maintenance:mode --off
app-hooks/post-installation/install-contacts-app.sh
+2
View File
@@ -1,3 +1,5 @@
#!/bin/bash
set -euox pipefail
php /var/www/html/occ app:enable contacts
app-hooks/post-installation/install-cookbook-app.sh
Executable
+5
View File
@@ -0,0 +1,5 @@
#!/bin/bash
set -euox pipefail
php /var/www/html/occ app:enable cookbook
app-hooks/post-installation/install-deck-app.sh
+2
View File
@@ -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
+2
View File
@@ -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
Executable
+22
View File
@@ -0,0 +1,22 @@
#!/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
# 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
+2
View File
@@ -1,3 +1,5 @@
#!/bin/bash
set -euox pipefail
php /var/www/html/occ app:enable tables
docker-compose.yml
+32 -8
View File
@@ -3,7 +3,7 @@ services:
# https://hub.docker.com/_/mariadb
db:
# Note: Check the recommend version here: https://docs.nextcloud.com/server/latest/admin_manual/installation/system_requirements.html#server
image: docker.io/library/mariadb:lts@sha256:4b1e7958f820681b1b93b9cf9ea05a76e0785da12699a1fb1d05e0eb2137e56b
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: docker.io/library/nextcloud:32.0.0@sha256:f4d0a4a74e93780db5e2130cdf08caa4cd856f6db4da34802d542d57443a9a63
#user: www-data:www-data
image: docker.io/library/nextcloud:32.0.0@sha256:4fbd72f05b5e6b82e078542b6cb2ecf021d2f8b5045454ffa7f4e080e488b375
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
@@ -43,6 +39,14 @@ services:
- MYSQL_DATABASE=nextcloud
- MYSQL_USER=nextcloud
- MYSQL_HOST=db
- REDIS_HOST=redis
recipes:
image: docker.io/library/nginx:alpine@sha256:61e01287e546aac28a3f56839c136b31f590273f3b41187a36f46f6a03bbfe22
restart: always
volumes:
- ./tests/fixtures/test_recipe.html:/usr/share/nginx/html/test_recipe.html:ro
- ./tests/fixtures/nginx.conf:/etc/nginx/nginx.conf:ro
unstructured:
image: downloads.unstructured.io/unstructured-io/unstructured-api:latest
@@ -55,6 +59,9 @@ services:
mcp:
build: .
command: ["--transport", "streamable-http"]
restart: always
depends_on:
- app
ports:
- 127.0.0.1:8000:8000
depends_on:
@@ -70,6 +77,23 @@ services:
#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
+161
View File
@@ -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/comparison-context-agent.md
+698
View File
@@ -0,0 +1,698 @@
# MCP Server Comparison: Nextcloud MCP Server vs Context Agent
This document compares the two MCP server implementations in the Nextcloud ecosystem:
1. **Nextcloud MCP Server** (this project) - Standalone MCP server for external access to Nextcloud
2. **Context Agent MCP Server** - MCP server embedded within Nextcloud as an External App
## Executive Summary
Both projects expose Nextcloud functionality via the Model Context Protocol (MCP), but serve different purposes and audiences:
- **Nextcloud MCP Server**: Brings Nextcloud OUT to external MCP clients (Claude Code, etc.)
- **Context Agent**: Brings external MCP servers IN to Nextcloud's AI Assistant
## Architecture Overview
```mermaid
graph TB
subgraph External["External Clients"]
CC[Claude Code]
IDE[IDEs with MCP]
APP[Other MCP Clients]
end
subgraph NMCP["Nextcloud MCP Server<br/>(This Project)"]
NMCP_Server[FastMCP Server]
NMCP_Client[HTTP Clients]
NMCP_Auth[OAuth/BasicAuth]
end
subgraph NC["Nextcloud Instance"]
subgraph CA["Context Agent ExApp"]
CA_Agent[LangGraph Agent]
CA_MCP[MCP Server /mcp]
CA_Tools[Tool Loader]
end
NC_Apps[Nextcloud Apps<br/>Notes, Calendar, Files, etc.]
NC_Assistant[Assistant App]
end
subgraph ExtMCP["External MCP Servers"]
Weather[Weather MCP]
Other[Other Services]
end
%% External clients connect to standalone MCP server
CC --> NMCP_Server
IDE --> NMCP_Server
APP --> NMCP_Server
%% Standalone MCP server talks to Nextcloud over HTTP
NMCP_Server --> NMCP_Auth
NMCP_Auth --> NMCP_Client
NMCP_Client -->|HTTP/HTTPS| NC_Apps
%% Context Agent is inside Nextcloud
CA_Agent --> CA_Tools
CA_Tools --> NC_Apps
CA_MCP -->|Exposes to| NC_Assistant
NC_Assistant -->|User requests| CA_Agent
%% Context Agent can consume external MCP servers
CA_Tools -->|Consumes| ExtMCP
%% Context Agent could consume Nextcloud MCP Server
CA_Tools -.->|Could consume| NMCP_Server
classDef external fill:#e1f5ff
classDef standalone fill:#fff4e1
classDef internal fill:#e8f5e9
class CC,IDE,APP external
class NMCP_Server,NMCP_Client,NMCP_Auth standalone
class CA_Agent,CA_MCP,CA_Tools,NC_Apps,NC_Assistant internal
```
## Deployment Models
```mermaid
graph LR
subgraph Deploy1["Nextcloud MCP Server Deployment"]
direction TB
D1[Docker Container]
D2[Cloud VM]
D3[Local Machine]
D4[Kubernetes Pod]
end
subgraph Deploy2["Context Agent Deployment"]
direction TB
NC[Nextcloud Instance<br/>with AppAPI]
ExApp[External App Container<br/>Managed by Nextcloud]
end
Deploy1 -.->|HTTP/HTTPS| NC
ExApp -->|Integrated| NC
classDef deploy fill:#fff4e1
classDef integrated fill:#e8f5e9
class D1,D2,D3,D4 deploy
class NC,ExApp integrated
```
### Nextcloud MCP Server
- **Location**: Runs anywhere with network access to Nextcloud
- **Deployment**: Docker, VM, local machine, Kubernetes
- **Connection**: HTTP/HTTPS to Nextcloud APIs
- **Independence**: Fully standalone service
### Context Agent
- **Location**: Runs inside Nextcloud as External App
- **Deployment**: Managed by Nextcloud AppAPI
- **Connection**: Native nc-py-api integration
- **Integration**: Deep Nextcloud integration
## Authentication Architecture
```mermaid
graph TB
subgraph NMCP_Auth["Nextcloud MCP Server Authentication"]
direction TB
Client1[MCP Client]
subgraph BasicAuth["BasicAuth Mode"]
BA_Shared[Shared NextcloudClient]
BA_Creds[Username + Password]
end
subgraph OAuth["OAuth Mode"]
OAuth_Token[OAuth Token]
OAuth_Verify[Token Verifier]
OAuth_OIDC[OIDC Discovery]
OAuth_Client[Per-Request Client]
end
Client1 -->|Basic Auth| BasicAuth
Client1 -->|Bearer Token| OAuth
BA_Creds --> BA_Shared
OAuth_Token --> OAuth_Verify
OAuth_OIDC --> OAuth_Verify
OAuth_Verify --> OAuth_Client
end
subgraph CA_Auth["Context Agent Authentication"]
direction TB
Client2[MCP Client]
CA_Header[Authorization Header]
CA_OCS[OCS API Validation]
CA_User[User Context]
CA_NC[nc-py-api Client]
Client2 --> CA_Header
CA_Header --> CA_OCS
CA_OCS -->|Extract user_id| CA_User
CA_User -->|nc.set_user| CA_NC
end
classDef auth fill:#fff4e1
classDef user fill:#e1f5ff
class BasicAuth,OAuth auth
class CA_User user
```
## Tool Registration & Loading
```mermaid
sequenceDiagram
participant Startup
participant NMCP as Nextcloud MCP<br/>Server
participant CA as Context Agent
participant Request as Client Request
Note over Startup,NMCP: Nextcloud MCP Server (Static)
Startup->>NMCP: Server starts
NMCP->>NMCP: configure_notes_tools(mcp)
NMCP->>NMCP: configure_calendar_tools(mcp)
NMCP->>NMCP: configure_contacts_tools(mcp)
Note over NMCP: Tools registered once<br/>at startup
Request->>NMCP: Call tool
NMCP->>NMCP: Use pre-registered tool
Note over Startup,CA: Context Agent (Dynamic)
Startup->>CA: Server starts
CA->>CA: Install ToolListMiddleware
Request->>CA: List tools (or 60s elapsed)
CA->>CA: get_tools(nc)
CA->>CA: Import all_tools/*.py
CA->>CA: Call module.get_tools(nc)
CA->>CA: Regenerate tool functions
Note over CA: Tools refreshed every 60s<br/>or on demand
Request->>CA: Call tool
CA->>CA: Regenerate with fresh nc
```
## Tool Definition Patterns
### Nextcloud MCP Server
```python
# Static registration at startup
def configure_notes_tools(mcp: FastMCP):
@mcp.tool()
async def nc_notes_create_note(
title: str,
content: str,
category: str,
ctx: Context
) -> CreateNoteResponse:
"""Create a new note"""
client = get_client(ctx) # Auto-detects auth mode
note_data = await client.notes.create_note(
title=title,
content=content,
category=category
)
return CreateNoteResponse(
id=note_data["id"],
title=note_data["title"],
etag=note_data["etag"]
)
# Resources for structured data access
@mcp.resource("nc://Notes/{note_id}")
async def nc_get_note_resource(note_id: int):
"""Get user note using note id"""
ctx = mcp.get_context()
client = get_client(ctx)
note_data = await client.notes.get_note(note_id)
return Note(**note_data)
```
**Key Features**:
- Native FastMCP `@mcp.tool()` decorator
- Pydantic models for type safety
- MCP Resources support
- Comprehensive error handling with McpError
- Context-based client resolution
### Context Agent
```python
# Dynamic loading at runtime
async def get_tools(nc: Nextcloud):
@tool
@safe_tool
def list_calendars():
"""List all existing calendars by name"""
principal = nc.cal.principal()
calendars = principal.calendars()
return ", ".join([cal.name for cal in calendars])
@tool
@dangerous_tool
def schedule_event(
calendar_name: str,
title: str,
description: str,
start_date: str,
end_date: str,
attendees: list[str] | None,
start_time: str | None,
end_time: str | None
):
"""Create a new event or meeting in a calendar"""
# Parse dates and times
start_datetime = datetime.strptime(start_date, "%Y-%m-%d")
# ... event creation logic
principal = nc.cal.principal()
calendar = {cal.name: cal for cal in calendars}[calendar_name]
calendar.add_event(str(c))
return True
return [list_calendars, schedule_event, ...]
def get_category_name():
return "Calendar and Tasks"
def is_available(nc: Nextcloud):
return True # or check capabilities
```
**Key Features**:
- LangChain `@tool` decorator
- `@safe_tool` / `@dangerous_tool` decorators
- Dynamic tool regeneration with fresh context
- Tools returned as list from async function
- Availability checking per module
## Client Architecture
```mermaid
graph TB
subgraph NMCP_Client["Nextcloud MCP Server Clients"]
direction TB
NMCP_Main[NextcloudClient]
NMCP_Base[BaseNextcloudClient]
NMCP_Notes[NotesClient]
NMCP_Cal[CalendarClient]
NMCP_Contacts[ContactsClient]
NMCP_Tables[TablesClient]
NMCP_WebDAV[WebDAVClient]
NMCP_Deck[DeckClient]
NMCP_Main --> NMCP_Notes
NMCP_Main --> NMCP_Cal
NMCP_Main --> NMCP_Contacts
NMCP_Main --> NMCP_Tables
NMCP_Main --> NMCP_WebDAV
NMCP_Main --> NMCP_Deck
NMCP_Notes -.->|extends| NMCP_Base
NMCP_Cal -.->|extends| NMCP_Base
NMCP_Contacts -.->|extends| NMCP_Base
NMCP_Base --> HTTPX["httpx.AsyncClient"]
NMCP_Base --> Retry["@retry_on_429"]
end
subgraph CA_Client["Context Agent Client"]
direction TB
CA_NC["nc-py-api<br/>NextcloudApp"]
CA_NC --> CA_Cal["nc.cal<br/>CalDAV"]
CA_NC --> CA_Talk["nc.talk<br/>Talk API"]
CA_NC --> CA_OCS["nc.ocs<br/>OCS API"]
CA_NC --> CA_Session["nc._session<br/>HTTP Adapter"]
end
HTTPX -->|"HTTP/HTTPS"| NextcloudAPI["Nextcloud APIs"]
CA_Session -->|"HTTP/HTTPS"| NextcloudAPI
classDef custom fill:#fff4e1
classDef native fill:#e8f5e9
class NMCP_Main,NMCP_Base,NMCP_Notes,NMCP_Cal custom
class CA_NC,CA_Cal,CA_Talk,CA_OCS native
```
## Functionality Comparison
### Available Tools & Features
| Feature Category | Nextcloud MCP Server | Context Agent MCP |
|-----------------|---------------------|-------------------|
| **Notes** | ✅ Full CRUD, search, attachments (7 tools) | ❌ Not implemented |
| **Calendar** | ✅ Full CalDAV (events, recurring, attendees) | ✅ Schedule events, list calendars, free/busy, tasks (4 tools) |
| **Contacts** | ✅ Full CardDAV (address books, contacts) | ✅ Find person, current user details (2 tools) |
| **Files** | ✅ Full WebDAV (read, write, directories) | ✅ Get content, folder tree, sharing (3 tools) |
| **Tables** | ✅ Row CRUD operations | ❌ Not implemented |
| **Deck** | ✅ Boards, stacks, cards | ✅ Create board, add card (2 tools) |
| **Talk** | ❌ Not implemented | ✅ List/send messages, create conversation (4 tools) |
| **Mail** | ❌ Not implemented | ✅ Send email, list mailboxes (2 tools) |
| **AI Features** | ❌ Not implemented | ✅ Image gen, audio2text, doc-gen, context_chat (4 tools) |
| **Web Search** | ❌ Not implemented | ✅ DuckDuckGo, YouTube search (2 tools) |
| **Location** | ❌ Not implemented | ✅ OpenStreetMap, HERE transit, weather (3 tools) |
| **OpenProject** | ❌ Not implemented | ✅ Integration (2 tools) |
| **MCP Resources** | ✅ notes://, nc:// URIs | ❌ Not supported |
| **External MCP** | ❌ Pure server only | ✅ Consumes external MCP servers |
| **Sharing** | ✅ Share management API | ❌ Not implemented |
| **Capabilities** | ✅ Server info resource | ❌ Not exposed |
### Tool Count Summary
- **Nextcloud MCP Server**: ~50+ tools and resources
- Deep integration with specific apps
- Full CRUD operations
- MCP Resources for structured data
- **Context Agent**: ~28+ tools
- Broader feature coverage
- Action-oriented (agent tasks)
- Can aggregate external MCP servers
## Tool Safety & Confirmation
### Context Agent Safety Model
```mermaid
graph TD
Request[User Request] --> Agent[LangGraph Agent]
Agent --> Model[LLM generates tool calls]
Model --> Check{Tool type?}
Check -->|"@safe_tool"| Execute[Execute immediately]
Check -->|"@dangerous_tool"| Queue[Queue for confirmation]
Queue --> UserNode[Request user confirmation]
UserNode -->|Approved| Execute
UserNode -->|Denied| Cancel[Cancel with reason]
Execute --> Result[Return result to agent]
Cancel --> Result
Result --> Agent
classDef safe fill:#e8f5e9
classDef danger fill:#ffe8e8
class Execute safe
class Queue,UserNode,Cancel danger
```
**Safe Tools** (read-only):
- `list_calendars`
- `find_person_in_contacts`
- `list_talk_conversations`
- `get_file_content`
- `get_folder_tree`
**Dangerous Tools** (write operations):
- `schedule_event`
- `send_message_to_conversation`
- `create_public_sharing_link`
- `send_email`
### Nextcloud MCP Server Safety
**No built-in safety classification**:
- All tools treated equally
- Relies on MCP client for validation
- OAuth scopes could control permissions
- User must review all actions
## Error Handling
### Nextcloud MCP Server
```python
try:
note_data = await client.notes.create_note(...)
return CreateNoteResponse(...)
except HTTPStatusError as e:
if e.response.status_code == 403:
raise McpError(ErrorData(
code=-1,
message="Access denied: insufficient permissions"
))
elif e.response.status_code == 413:
raise McpError(ErrorData(
code=-1,
message="Note content too large"
))
elif e.response.status_code == 409:
raise McpError(ErrorData(
code=-1,
message="Note with this title already exists"
))
```
**Features**:
- Comprehensive HTTP status code handling
- User-friendly error messages
- Specific error codes
- Guidance on resolution
### Context Agent
```python
def schedule_event(...):
"""Create event"""
# ... implementation
calendar.add_event(str(c))
return True # Simple boolean return
```
**Features**:
- Minimal error handling
- Exceptions propagate to agent
- LangChain handles retries
- Agent interprets failures
## Use Cases
### When to Use Nextcloud MCP Server
```mermaid
graph LR
Root[Nextcloud MCP Server]
Root --> ExtAccess[External Access]
Root --> OAuth[OAuth Security]
Root --> DeepAPI[Deep API Access]
Root --> Deploy[Standalone Deployment]
ExtAccess --> EA1[Claude Code integration]
ExtAccess --> EA2[IDE plugins with MCP]
ExtAccess --> EA3[Custom MCP clients]
ExtAccess --> EA4[Cross-platform tools]
OAuth --> O1[Token-based auth]
OAuth --> O2[OIDC compliance]
OAuth --> O3[Per-user permissions]
OAuth --> O4[Secure external access]
DeepAPI --> DA1[Full CRUD operations]
DeepAPI --> DA2[Notes management]
DeepAPI --> DA3[Calendar CalDAV]
DeepAPI --> DA4[Contacts CardDAV]
DeepAPI --> DA5[File operations]
DeepAPI --> DA6[Table data]
Deploy --> D1[Docker containers]
Deploy --> D2[Cloud VMs]
Deploy --> D3[Kubernetes]
Deploy --> D4[On-premise servers]
classDef rootStyle fill:#4a90e2,stroke:#2e5c8a,color:#fff
classDef categoryStyle fill:#f39c12,stroke:#d68910,color:#fff
classDef itemStyle fill:#e8f5e9,stroke:#81c784
class Root rootStyle
class ExtAccess,OAuth,DeepAPI,Deploy categoryStyle
class EA1,EA2,EA3,EA4,O1,O2,O3,O4,DA1,DA2,DA3,DA4,DA5,DA6,D1,D2,D3,D4 itemStyle
```
**Best for**:
1. External clients accessing Nextcloud (Claude Code, IDEs)
2. OAuth/OIDC authentication requirements
3. Full CRUD on Notes, Calendar, Contacts, Tables
4. WebDAV file system access
5. MCP Resources for structured data
6. Flexible deployment scenarios
7. Building external integrations
### When to Use Context Agent MCP Server
```mermaid
graph LR
Root[Context Agent MCP]
Root --> Assistant[AI Assistant]
Root --> ActionOriented[Action-Oriented]
Root --> MCPAgg[MCP Aggregation]
Root --> Safety[Safety Features]
Assistant --> A1[Nextcloud UI integration]
Assistant --> A2[Task Processing API]
Assistant --> A3[User requests in Assistant]
Assistant --> A4[Human-in-the-loop]
ActionOriented --> AO1[Send emails]
ActionOriented --> AO2[Create calendar events]
ActionOriented --> AO3[Post Talk messages]
ActionOriented --> AO4[Generate images]
ActionOriented --> AO5[Search web]
MCPAgg --> M1[Consume external MCP servers]
MCPAgg --> M2[Weather services]
MCPAgg --> M3[Maps and transit]
MCPAgg --> M4[Custom integrations]
MCPAgg --> M5[Unified tool interface]
Safety --> S1[Read operations auto-execute]
Safety --> S2[Write operations require approval]
Safety --> S3[User confirmation flow]
Safety --> S4[Agent safety]
classDef rootStyle fill:#9b59b6,stroke:#6c3483,color:#fff
classDef categoryStyle fill:#e74c3c,stroke:#c0392b,color:#fff
classDef itemStyle fill:#fff4e1,stroke:#f39c12
class Root rootStyle
class Assistant,ActionOriented,MCPAgg,Safety categoryStyle
class A1,A2,A3,A4,AO1,AO2,AO3,AO4,AO5,M1,M2,M3,M4,M5,S1,S2,S3,S4 itemStyle
```
**Best for**:
1. AI-driven actions inside Nextcloud UI
2. Assistant app integration
3. Safe/dangerous tool distinction
4. Talk, Mail, Deck operations
5. AI features (image gen, audio2text)
6. Web search and maps
7. Aggregating external MCP servers
8. Agent acting on behalf of users
## Complementary Architecture
The two MCP servers can work together in complementary ways:
```mermaid
graph TB
User[User] -->|Requests AI assistance| Assistant[Nextcloud Assistant App]
Assistant --> ContextAgent[Context Agent]
subgraph ContextAgent["Context Agent (Inside Nextcloud)"]
direction TB
Agent[LangGraph Agent]
MCPServer[MCP Server /mcp]
ToolLoader[Tool Loader]
Agent --> ToolLoader
ToolLoader --> InternalTools[Internal Tools<br/>Talk, Mail, Calendar]
end
subgraph ExternalMCP["External MCP Ecosystem"]
NextcloudMCP[Nextcloud MCP Server<br/>This Project]
WeatherMCP[Weather MCP]
CustomMCP[Custom MCP Services]
end
ToolLoader -->|Consumes| NextcloudMCP
ToolLoader -->|Consumes| WeatherMCP
ToolLoader -->|Consumes| CustomMCP
subgraph ExternalClients["External Clients"]
Claude[Claude Code]
IDE[IDEs with MCP]
end
Claude -->|Direct access| NextcloudMCP
IDE -->|Direct access| NextcloudMCP
NextcloudMCP -->|OAuth/HTTP| NextcloudApps[Nextcloud Apps<br/>Notes, Calendar, Files]
InternalTools -->|nc-py-api| NextcloudApps
classDef internal fill:#e8f5e9
classDef external fill:#e1f5ff
classDef mcp fill:#fff4e1
class Assistant,Agent,MCPServer,ToolLoader,InternalTools,NextcloudApps internal
class Claude,IDE external
class NextcloudMCP,WeatherMCP,CustomMCP mcp
```
### Example Workflows
**Workflow 1: External Client → Nextcloud MCP Server**
```
Claude Code → Nextcloud MCP Server → Nextcloud Notes API
```
- User asks Claude Code to search notes
- Claude Code calls `nc_notes_search_notes` tool
- Returns results directly to user
**Workflow 2: Assistant → Context Agent → Internal Tools**
```
User → Assistant → Context Agent → Send Email Tool
```
- User asks Assistant to send an email
- Context Agent identifies "send_email" as dangerous
- Requests user confirmation
- Sends email via nc-py-api
**Workflow 3: Assistant → Context Agent → External MCP**
```
User → Assistant → Context Agent → Nextcloud MCP Server → Notes
```
- User asks Assistant about notes
- Context Agent consumes Nextcloud MCP Server as external MCP
- Gets notes data via MCP protocol
- Returns to user via Assistant
## Technical Comparison Matrix
| Aspect | Nextcloud MCP Server | Context Agent MCP |
|--------|---------------------|-------------------|
| **Framework** | FastMCP (native) | FastMCP + LangChain |
| **Tool Decorator** | `@mcp.tool()` | `@tool` from LangChain |
| **Tool Loading** | Static (startup) | Dynamic (runtime) |
| **Tool Refresh** | No (restart required) | Every 60 seconds |
| **Resources** | Yes (`@mcp.resource()`) | No |
| **Transports** | SSE, HTTP, Streamable-HTTP | Stateless HTTP only |
| **MCP Mode** | Server only | Server + Client (hybrid) |
| **Client Type** | httpx (custom HTTP) | nc-py-api (native) |
| **Deployment** | Standalone external | Inside Nextcloud (ExApp) |
| **Auth** | BasicAuth or OAuth/OIDC | Session-based (ExApp) |
| **User Context** | Shared or per-token | Per-request `nc.set_user()` |
| **Error Handling** | McpError with codes | Basic exceptions |
| **Type Safety** | Pydantic models | Python types |
| **Safety Model** | No built-in | Safe/Dangerous classification |
| **Dependencies** | FastMCP, httpx, Pydantic | nc-py-api, LangChain, LangGraph |
| **Integration** | HTTP APIs | AppAPI + Task Processing |
| **External MCP** | No | Yes (consumes) |
## Summary
Both MCP servers serve important but different roles in the Nextcloud ecosystem:
### Nextcloud MCP Server (This Project)
- **Purpose**: Expose Nextcloud to external MCP clients
- **Strength**: Deep CRUD operations, OAuth security, standalone deployment
- **Audience**: External developers, Claude Code users, integration builders
### Context Agent MCP Server
- **Purpose**: Bring AI agent capabilities to Nextcloud users
- **Strength**: Action-oriented, safe/dangerous tools, MCP aggregation
- **Audience**: Nextcloud users via Assistant app, AI-driven workflows
**Key Insight**: These are complementary, not competing. Context Agent could even consume Nextcloud MCP Server as one of its external MCP sources, creating a unified ecosystem where:
- External clients access Nextcloud via Nextcloud MCP Server
- Internal users leverage Context Agent for AI assistance
- Context Agent aggregates both internal tools and external MCP servers (including Nextcloud MCP Server)
docs/configuration.md
+253
View File
@@ -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/cookbook.md
+189
View File
@@ -0,0 +1,189 @@
# Cookbook App
### Cookbook Tools
| Tool | Description |
|------|-------------|
| `nc_cookbook_import_recipe` | Import a recipe from a URL using schema.org metadata |
| `nc_cookbook_create_recipe` | Create a new recipe with all schema.org fields |
| `nc_cookbook_get_recipe` | Get a specific recipe by ID |
| `nc_cookbook_update_recipe` | Update an existing recipe |
| `nc_cookbook_delete_recipe` | Delete a recipe permanently |
| `nc_cookbook_list_recipes` | Get all recipes in the database |
| `nc_cookbook_search_recipes` | Search for recipes by keywords, tags, and categories |
| `nc_cookbook_list_categories` | Get all known recipe categories |
| `nc_cookbook_get_recipes_in_category` | Get all recipes in a specific category |
| `nc_cookbook_list_keywords` | Get all known recipe keywords/tags |
| `nc_cookbook_get_recipes_with_keywords` | Get all recipes that have specific keywords |
| `nc_cookbook_set_config` | Set Cookbook app configuration |
| `nc_cookbook_reindex` | Trigger a rescan of all recipes into the search database |
### Cookbook Resources
| Resource | Description |
|----------|-------------|
| `cookbook://version` | Get Cookbook app and API version information |
| `cookbook://config` | Get Cookbook app configuration |
| `nc://Cookbook/{recipe_id}` | Get a specific recipe by ID |
## Recipe Management
The server provides complete Nextcloud Cookbook integration, enabling you to manage your recipe collection:
- **Import recipes from websites** using schema.org metadata
- Full CRUD operations for recipes
- Search and organize with categories and keywords
- Support for structured recipe data (ingredients, instructions, nutrition, etc.)
- Configure app settings and trigger reindexing
### Schema.org Recipe Format
The Cookbook app uses the [schema.org/Recipe](https://schema.org/Recipe) specification for structured recipe data. This standard format includes:
- **Basic info**: Name, description, image, URL
- **Timing**: Preparation time, cooking time, total time (ISO8601 format like `PT30M`)
- **Ingredients**: List of ingredients with quantities
- **Instructions**: Step-by-step cooking instructions
- **Metadata**: Category, keywords/tags, yield (servings)
- **Nutrition**: Optional nutrition information
### Usage Examples
#### Import Recipe from URL
Many recipe websites include schema.org metadata. The import tool automatically extracts this data:
```python
# Import from a recipe website
await nc_cookbook_import_recipe(
url="https://www.example.com/recipes/chocolate-cake"
)
# Returns: Recipe object with all extracted data
```
#### Create Recipe Manually
```python
# Create a new recipe from scratch
await nc_cookbook_create_recipe(
name="Homemade Pizza",
description="Classic homemade pizza with fresh ingredients",
ingredients=[
"500g pizza dough",
"200g tomato sauce",
"300g mozzarella cheese",
"Fresh basil leaves",
"Olive oil"
],
instructions=[
"Preheat oven to 250°C (480°F)",
"Roll out the pizza dough",
"Spread tomato sauce evenly",
"Add mozzarella cheese",
"Bake for 10-12 minutes",
"Top with fresh basil and olive oil"
],
category="Main Course",
keywords="italian,vegetarian,quick",
prep_time="PT20M", # 20 minutes
cook_time="PT12M", # 12 minutes
total_time="PT32M", # 32 minutes
recipe_yield=4 # 4 servings
)
```
#### Update Recipe
```python
# Update recipe details (only specified fields are changed)
await nc_cookbook_update_recipe(
recipe_id=123,
description="Updated: Classic homemade pizza - now with video tutorial!",
url="https://example.com/videos/pizza-tutorial",
keywords="italian,vegetarian,quick,video"
)
```
#### Search and Filter
```python
# Search recipes by keyword
results = await nc_cookbook_search_recipes(query="chocolate")
# List all categories
categories = await nc_cookbook_list_categories()
# Returns: [{"name": "Desserts", "recipe_count": 15}, ...]
# Get recipes in a category
desserts = await nc_cookbook_get_recipes_in_category(category="Desserts")
# List all keywords/tags
keywords = await nc_cookbook_list_keywords()
# Returns: [{"name": "chocolate", "recipe_count": 8}, ...]
# Get recipes with specific tags
quick_meals = await nc_cookbook_get_recipes_with_keywords(keywords=["quick", "30min"])
```
#### Manage Configuration
```python
# Configure the Cookbook app
await nc_cookbook_set_config(
folder="Recipes", # Folder path in user's files
update_interval=15, # Auto-rescan every 15 minutes
print_image=True # Print images with recipes
)
# Trigger manual reindex after file changes
await nc_cookbook_reindex()
```
### Time Format (ISO8601 Duration)
Recipe times use ISO8601 duration format:
| Duration | Format | Example |
|----------|--------|---------|
| 15 minutes | `PT15M` | Prep time |
| 1 hour | `PT1H` | Baking time |
| 1 hour 30 minutes | `PT1H30M` | Total time |
| 45 seconds | `PT45S` | Mixing time |
| 2 hours 15 minutes | `PT2H15M` | Slow cooking |
### Tips for Recipe Import
**Best practices for importing recipes from URLs:**
1. **Look for schema.org support**: Most modern recipe sites include schema.org metadata
2. **Check import quality**: Review imported recipes for completeness
3. **Handle duplicates**: The API prevents duplicate imports by recipe name
4. **Edit after import**: Update imported recipes with personal notes or adjustments
**Common recipe websites with good schema.org support:**
- AllRecipes
- Food Network
- BBC Good Food
- Serious Eats
- Bon Appétit
- Many food blogs using recipe plugins
### Organizing Your Recipes
**Categories**: Organize recipes by type (Appetizers, Main Course, Desserts, etc.)
- Use `nc_cookbook_list_categories` to see all categories
- Filter by category with `nc_cookbook_get_recipes_in_category`
**Keywords/Tags**: Tag recipes with searchable terms (vegetarian, quick, spicy, etc.)
- Use `nc_cookbook_list_keywords` to see all tags
- Filter by tags with `nc_cookbook_get_recipes_with_keywords`
- Search across all fields with `nc_cookbook_search_recipes`
**Reindexing**: The Cookbook app maintains a search index
- Automatically scans at configured intervals
- Manually trigger with `nc_cookbook_reindex` after bulk changes
- Required after modifying recipe files directly in WebDAV
## API Reference
For detailed API documentation, see the [Nextcloud Cookbook OpenAPI specification](https://github.com/nextcloud/cookbook/tree/master/docs/dev/api/0.1.2).
docs/installation.md
+215
View File
@@ -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
+319
View File
@@ -0,0 +1,319 @@
# 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 a client on first startup
3. Saves credentials to `.nextcloud_oauth_client.json`
4. Reuses these credentials on subsequent startups
5. Re-registers only if credentials are missing or expired
**Best for**: Development, testing, quick 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/client/test_oauth_playwright.py`](../tests/client/test_oauth_playwright.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/client/test_oauth_playwright.py --browser firefox -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
+545
View File
@@ -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, quick deployments
**How it works**:
- MCP server automatically registers an OAuth client on first startup
- Uses Nextcloud's dynamic client registration endpoint
- Saves credentials to `.nextcloud_oauth_client.json`
- Reuses stored credentials on subsequent restarts
- Re-registers automatically if credentials expire
**Pros**:
- Zero configuration required
- Quick setup
- Automatic credential management
**Cons**:
- Clients expire (default: 1 hour, configurable)
- Must have dynamic client registration enabled on Nextcloud
**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 an OAuth client via Nextcloud CLI
- Provide client credentials to MCP server via environment variables
- 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
+554
View File
@@ -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
+242
View File
@@ -0,0 +1,242 @@
# 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 (RFC 7636)
**Status**: ✅ **Complete** (Merged Upstream)
**Affected Component**: `oidc` app
**Issue**: The OIDC app lacked PKCE (Proof Key for Code Exchange) implementation per RFC 7636.
**Resolution**: Full PKCE support has been implemented and merged upstream into the `oidc` app:
**Authorization Endpoint** (`/authorize`):
- Accepts `code_challenge` and `code_challenge_method` parameters
- Validates code_challenge format (43-128 characters, unreserved chars only)
- Supports both `S256` (SHA-256) and `plain` challenge methods
- Stores challenge and method in database for later verification
**Token Endpoint** (`/token`):
- Accepts `code_verifier` parameter
- Verifies code_verifier against stored code_challenge using proper algorithm
- Uses constant-time comparison to prevent timing attacks
- Enforces code_verifier requirement when PKCE was used in authorization
**Discovery Document**:
```json
{
"code_challenge_methods_supported": ["S256", "plain"]
}
```
**Database**:
- New columns: `code_challenge` and `code_challenge_method` in `oc_oauth2_access_tokens`
- Migration included for existing installations
**Why It Mattered**:
- MCP specification requires PKCE with S256 code challenge method
- RFC 7636 PKCE provides security for public clients (no client secret)
- RFC 8414 states that absence of `code_challenge_methods_supported` means PKCE is **not supported**
- Prevents authorization code interception attacks
**Upstream PR**: [H2CK/oidc#584](https://github.com/H2CK/oidc/pull/584) - ✅ **Merged 2025-10-20**
- **Changes**: Complete PKCE implementation (+194 lines)
- Authorization flow with code_challenge validation
- Token exchange with code_verifier verification
- Database schema updates
- Discovery document updates
- **Status**: Merged and available in v1.10.0+ of the `oidc` app
---
## 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` | ✅ Merged | ~~Medium~~ | ✅ PKCE advertisement complete (v1.10.0+) |
## What Works Without Patches
The following functionality works **out of the box** without any patches:
✅ **OAuth Flow**:
- OIDC discovery with full PKCE support (requires `oidc` app v1.10.0+)
- Dynamic client registration
- Authorization code flow with PKCE (S256 and plain methods)
- Token exchange with code_verifier verification
- 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**: Now complete with `oidc` app v1.10.0+
- ✅ Full RFC 8414 compliance (PKCE advertisement)
- ✅ 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/client/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-20
**Next Review**: When issue #1221 (Bearer token support) has activity
docs/quickstart-oauth.md
+163
View File
@@ -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
- Quick deployments
For **production deployments**, consider:
1. Pre-registering OAuth client manually
2. Using dedicated client credentials that don't expire
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
+440
View File
@@ -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/testing-client-sessions-architecture.md
+317
View File
@@ -0,0 +1,317 @@
# Testing Client Sessions Architecture
## Overview
This document compares different approaches to managing MCP client sessions in integration tests, addressing the fundamental incompatibility between pytest-asyncio's fixture management and anyio's structured concurrency requirements.
## The Problem
When using pytest-asyncio with anyio-based libraries (like the MCP Python SDK), session-scoped async generator fixtures encounter a fundamental issue:
1. **pytest-asyncio** runs fixture teardown in a **new asyncio task** using `runner.run()`
2. **anyio** requires that cancel scopes be entered and exited in the **same task**
3. This causes `RuntimeError: Attempted to exit cancel scope in a different task than it was entered in`
This is a **known limitation** documented in the anyio project and is not a bug in either pytest-asyncio or anyio, but rather an inherent incompatibility between their design philosophies.
## Solution Comparison
### Solution 1: Native Async Context Managers with Surgical Exception Handling ✅ **IMPLEMENTED**
**Approach**: Use native `async with` statements for clean code structure, but add targeted exception handling at the pytest fixture level to handle the expected teardown errors.
**Implementation**:
```python
async def create_mcp_client_session(
url: str,
token: str | None = None,
client_name: str = "MCP",
) -> AsyncGenerator[ClientSession, Any]:
"""Uses native async context managers for clean LIFO cleanup."""
headers = {"Authorization": f"Bearer {token}"} if token else None
async with streamablehttp_client(url, headers=headers) as (read_stream, write_stream, _):
async with ClientSession(read_stream, write_stream) as session:
await session.initialize()
yield session
@pytest.fixture(scope="session")
async def nc_mcp_client() -> AsyncGenerator[ClientSession, Any]:
"""Fixture with surgical exception handling for pytest-asyncio incompatibility."""
try:
async for session in create_mcp_client_session(
url="http://127.0.0.1:8000/mcp", client_name="Basic MCP"
):
yield session
except RuntimeError as e:
# Only catch the specific expected error during pytest teardown
if "cancel scope" in str(e) and "different task" in str(e):
logger.debug(f"Ignoring expected pytest-asyncio teardown issue: {e}")
else:
# Unexpected RuntimeError - re-raise to fail the test
raise
```
**Pros**:
- ✅ Clean, idiomatic code using native Python context managers
- ✅ Exception handling is surgical - only catches the specific expected error
- ✅ Unexpected errors still propagate and fail tests
- ✅ Can use session-scoped fixtures for performance
- ✅ Easy to understand and maintain
- ✅ Minimal code changes from original implementation
- ✅ No external dependencies required
**Cons**:
- ⚠️ Still requires exception suppression (though targeted)
- ⚠️ String-based exception matching is somewhat fragile
- ⚠️ Must apply the pattern to each session-scoped fixture
- ⚠️ Doesn't solve the root cause
**Verdict**: **Recommended** - Best balance of code clarity, maintainability, and pragmatism.
---
### Solution 2: Task-Isolated Fixtures
**Approach**: Run each fixture's client session in an isolated anyio task group, allowing independent cleanup without cross-fixture interference.
**Implementation**:
```python
@pytest.fixture(scope="session")
async def nc_mcp_client() -> AsyncGenerator[ClientSession, Any]:
"""Fixture with task isolation for clean teardown."""
import anyio
session_holder = {"session": None}
async def create_and_hold_session():
"""Runs in isolated task - creates session and keeps it alive."""
async with streamablehttp_client("http://127.0.0.1:8000/mcp") as (read_stream, write_stream, _):
async with ClientSession(read_stream, write_stream) as session:
await session.initialize()
session_holder["session"] = session
# Keep session alive until cancelled
try:
await anyio.sleep_forever()
except anyio.get_cancelled_exc_class():
pass # Expected cancellation
async with anyio.create_task_group() as tg:
tg.start_soon(create_and_hold_session)
# Wait for session to be ready
while session_holder["session"] is None:
await anyio.sleep(0.1)
yield session_holder["session"]
# Task group cancellation ensures clean LIFO cleanup
tg.cancel_scope.cancel()
```
**Pros**:
- ✅ No exception suppression needed
- ✅ Each fixture has its own isolated task scope
- ✅ More theoretically correct approach
- ✅ Can use session-scoped fixtures
**Cons**:
- ❌ Significantly more complex code
- ❌ Harder to understand for developers unfamiliar with anyio
- ❌ Requires understanding of task groups and cancel scopes
- ❌ More boilerplate per fixture
- ❌ Still doesn't solve the fundamental pytest-asyncio incompatibility
- ❌ Polling for session readiness is inelegant
- ❌ Higher cognitive overhead for maintenance
**Verdict**: **Not Recommended** - Complexity outweighs benefits. Consider only if exception handling is completely unacceptable.
---
### Solution 3: Function-Scoped Fixtures with Nested Context Managers
**Approach**: Change fixtures to function scope and rely on Python's context manager nesting for guaranteed LIFO cleanup.
**Implementation**:
```python
@pytest.fixture(scope="function") # Changed from session
async def nc_mcp_client() -> AsyncGenerator[ClientSession, Any]:
"""Function-scoped fixture with natural LIFO cleanup."""
async with streamablehttp_client("http://127.0.0.1:8000/mcp") as (read_stream, write_stream, _):
async with ClientSession(read_stream, write_stream) as session:
await session.initialize()
yield session
# For tests needing multiple clients:
@pytest.fixture(scope="function")
async def multi_mcp_clients() -> AsyncGenerator[tuple[ClientSession, ClientSession], Any]:
"""Multiple clients with guaranteed LIFO cleanup through nesting."""
async with streamablehttp_client("http://127.0.0.1:8000/mcp") as (read1, write1, _):
async with ClientSession(read1, write1) as session1:
await session1.initialize()
async with streamablehttp_client("http://127.0.0.1:8001/mcp") as (read2, write2, _):
async with ClientSession(read2, write2) as session2:
await session2.initialize()
yield session1, session2
# Cleanup: session2 -> stream2 -> session1 -> stream1 (LIFO guaranteed)
```
**Pros**:
- ✅ No exception handling needed
- ✅ Simplest to understand
- ✅ Natural LIFO cleanup through Python's context managers
- ✅ Each test gets fresh clients (better isolation)
- ✅ No workarounds or hacks required
**Cons**:
- ❌ Significantly slower tests (new clients per test)
- ❌ Cannot share client state across tests
- ❌ More resource intensive
- ❌ Higher overhead for test suite execution
- ❌ May not be practical for expensive fixtures (e.g., OAuth tokens)
- ❌ Nested context managers become unwieldy with many clients
**Verdict**: **Good Alternative** - Consider for specific fixtures where session scope isn't critical, or for new test files where performance isn't a concern.
---
### Solution 4: Use pytest-trio Instead of pytest-asyncio (Future)
**Approach**: Replace pytest-asyncio with pytest-trio, which was designed with structured concurrency in mind.
**Implementation**:
```python
# pyproject.toml
[tool.pytest.ini_options]
# Remove: asyncio_mode = "auto"
# Add: trio_mode = "auto"
# Fixtures work naturally with trio
@pytest.fixture(scope="session")
async def nc_mcp_client() -> AsyncGenerator[ClientSession, Any]:
async with streamablehttp_client("http://127.0.0.1:8000/mcp") as (read, write, _):
async with ClientSession(read, write) as session:
await session.initialize()
yield session
```
**Pros**:
- ✅ No workarounds needed
- ✅ Designed for structured concurrency
- ✅ Theoretically cleanest solution
- ✅ Can use session-scoped fixtures naturally
**Cons**:
- ❌ Requires switching from asyncio to trio backend
- ❌ Major refactoring required
- ❌ May break existing code that assumes asyncio
- ❌ Dependency changes throughout project
- ❌ Team needs to learn trio ecosystem
- ❌ Less ecosystem support than asyncio
**Verdict**: **Not Practical** - Too disruptive for existing projects. Consider only for greenfield projects or major rewrites.
---
## Decision Matrix
| Solution | Code Clarity | Maintenance | Performance | Safety | Effort |
|----------|--------------|-------------|-------------|--------|--------|
| **Solution 1** (Implemented) | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ |
| Solution 2 (Task-Isolated) | ⭐⭐ | ⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐ |
| Solution 3 (Function-Scoped) | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ |
| Solution 4 (pytest-trio) | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐ |
## Implementation Details
### What Changed in Solution 1
1. **`create_mcp_client_session` function** (conftest.py:61-110):
- Replaced manual `__aenter__`/`__aexit__` calls with native `async with` statements
- Removed blanket exception suppression from cleanup logic
- Added clear documentation about LIFO cleanup order
- Simplified from ~60 lines to ~40 lines
2. **Session-scoped MCP client fixtures** (conftest.py:148-1269):
- Added targeted exception handling wrapper
- Only catches specific "cancel scope" + "different task" RuntimeError
- All other exceptions propagate normally
- Applied to: `nc_mcp_client`, `nc_mcp_oauth_client`, `alice_mcp_client`, `bob_mcp_client`, `charlie_mcp_client`, `diana_mcp_client`
3. **Documentation**:
- Added comprehensive docstrings explaining the workaround
- Referenced MCP SDK issue #577 for context
- Documented why this is necessary and not a bug
### Benefits of This Implementation
1. **Clean Core Logic**: The `create_mcp_client_session` function is now clean, idiomatic Python with no workarounds
2. **Isolated Workaround**: Exception handling is confined to pytest fixture level where the issue actually occurs
3. **Surgical Exception Handling**: Only catches the specific expected error, not all RuntimeErrors
4. **Performance**: Maintains session-scoped fixtures for fast test execution
5. **Maintainability**: Easy to understand and modify
6. **Safety**: Real errors still cause test failures
## Testing Results
All tests pass cleanly with the implementation:
```bash
$ uv run pytest tests/server/test_mcp.py -v
============================================= test session starts ==============================================
tests/server/test_mcp.py::test_mcp_connectivity PASSED [ 16%]
tests/server/test_mcp.py::test_mcp_notes_crud_workflow PASSED [ 33%]
tests/server/test_mcp.py::test_mcp_notes_etag_conflict PASSED [ 50%]
tests/server/test_mcp.py::test_mcp_webdav_workflow PASSED [ 66%]
tests/server/test_mcp.py::test_mcp_resources_access PASSED [ 83%]
tests/server/test_mcp.py::test_mcp_calendar_workflow PASSED [100%]
============================================== 6 passed in 39.52s ==============================================
```
## Recommendations
### For This Project: Solution 1 ✅
The implemented solution (Solution 1) is the best fit because:
- Minimal disruption to existing tests
- Clean, maintainable code
- Good performance with session-scoped fixtures
- Targeted exception handling that doesn't hide real errors
### For New Test Files: Consider Solution 3
For new test files where performance isn't critical, consider using function-scoped fixtures (Solution 3):
- No workarounds needed
- Perfect code clarity
- Better test isolation
### For Greenfield Projects: Consider Solution 4
For new projects starting from scratch, consider pytest-trio instead of pytest-asyncio:
- Native structured concurrency support
- No workarounds needed
- Better alignment with modern async Python patterns
## Related Resources
- [MCP Python SDK Issue #577](https://github.com/modelcontextprotocol/python-sdk/issues/577) - Original issue report
- [Anyio Issue #345](https://github.com/agronholm/anyio/issues/345) - Discussion of fixture limitations
- [Nextcloud MCP Note 378555](nextcloud://notes/378555) - Detailed investigation notes
- pytest-asyncio documentation: https://pytest-asyncio.readthedocs.io/
- anyio structured concurrency guide: https://anyio.readthedocs.io/en/stable/basics.html
## Appendix: Why Can't This Be Fixed Upstream?
The incompatibility cannot be "fixed" in either pytest-asyncio or anyio without breaking their core design:
1. **pytest-asyncio** needs to manage fixture lifecycle across different scopes, requiring separate task creation for cleanup
2. **anyio** enforces structured concurrency guarantees by requiring same-task cancel scope entry/exit
3. These requirements are fundamentally incompatible
The maintainers of both projects are aware of this issue, and it's considered an acceptable trade-off given their respective design goals. The recommended approach is to handle it at the application level, as we've done here.
docs/troubleshooting.md
+556
View File
@@ -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
+20
View File
@@ -1,4 +1,24 @@
# 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
+472 -40
View File
@@ -1,62 +1,370 @@
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 httpx
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 LOGGING_CONFIG, 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_cookbook_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
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
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
_, 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,8 +372,10 @@ 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,
"cookbook": configure_cookbook_tools,
"deck": configure_deck_tools,
}
@@ -101,16 +411,19 @@ 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(
"--log-level",
"-l",
default="info",
show_default=True,
type=click.Choice(["critical", "error", "warning", "info", "debug", "trace"]),
help="Logging level",
)
@click.option(
"--transport",
@@ -118,40 +431,159 @@ def get_app(transport: str = "sse", enabled_apps: list[str] | None = None):
default="sse",
show_default=True,
type=click.Choice(["sse", "streamable-http", "http"]),
help="MCP transport protocol",
)
@click.option(
"--enable-app",
"-e",
multiple=True,
type=click.Choice(["notes", "tables", "webdav", "calendar", "contacts", "deck"]),
type=click.Choice(
["notes", "tables", "webdav", "calendar", "contacts", "cookbook", "deck"]
),
help="Enable specific Nextcloud app APIs. Can be specified multiple times. If not specified, all apps are enabled.",
)
@click.option(
"--oauth/--no-oauth",
default=None,
help="Force OAuth mode (if enabled) or BasicAuth mode (if disabled). By default, auto-detected based on environment variables.",
)
@click.option(
"--oauth-client-id",
envvar="NEXTCLOUD_OIDC_CLIENT_ID",
help="OAuth client ID (can also use NEXTCLOUD_OIDC_CLIENT_ID env var)",
)
@click.option(
"--oauth-client-secret",
envvar="NEXTCLOUD_OIDC_CLIENT_SECRET",
help="OAuth client secret (can also use NEXTCLOUD_OIDC_CLIENT_SECRET env var)",
)
@click.option(
"--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,
workers: int,
reload: bool,
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:
app = "nextcloud_mcp_server.app:get_app"
factory = True
else:
app = get_app(transport=transport, enabled_apps=enabled_apps)
factory = False
app = get_app(transport=transport, enabled_apps=enabled_apps)
uvicorn.run(
app=app,
factory=factory,
host=host,
port=port,
reload=reload,
workers=workers,
log_level=log_level,
app=app, host=host, port=port, log_level=log_level, log_config=LOGGING_CONFIG
)
nextcloud_mcp_server/auth/__init__.py
+14
View File
@@ -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
+34
View File
@@ -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
+261
View File
@@ -0,0 +1,261 @@
"""Dynamic client registration for Nextcloud OIDC."""
import datetime as dt
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')}"
)
expires_at = dt.datetime.fromtimestamp(
client_info.get("client_secret_expires_at")
)
logger.info(
f"Client expires at: {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,
) -> 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 (no stored credentials or expired)
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
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
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
+65
View File
@@ -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
+207
View File
@@ -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
+34 -6
View File
@@ -2,21 +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 .cookbook import CookbookClient
from .deck import DeckClient
from .groups import GroupsClient
from .notes import NotesClient
from .sharing import SharingClient
from .tables import TablesClient
from .users import UsersClient
from .webdav import WebDAVClient
logger = logging.getLogger(__name__)
@@ -68,9 +72,15 @@ class NextcloudClient:
self.notes = NotesClient(self._client, username)
self.webdav = WebDAVClient(self._client, username)
self.tables = TablesClient(self._client, username)
self.calendar = CalendarClient(self._client, username)
self.calendar = CalendarClient(
base_url, username, auth
) # Uses AsyncDavClient internally
self.contacts = ContactsClient(self._client, username)
self.cookbook = CookbookClient(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 +95,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",
@@ -96,13 +123,14 @@ class NextcloudClient:
async def notes_search_notes(self, *, query: str):
"""Search notes using token-based matching with relevance ranking."""
all_notes = await self.notes.get_all_notes()
return self._notes_search.search_notes(all_notes, query)
all_notes = self.notes.get_all_notes()
return await self._notes_search.search_notes(all_notes, query)
def _get_webdav_base_path(self) -> str:
"""Helper to get the base WebDAV path for the authenticated user."""
return f"/remote.php/dav/files/{self.username}"
async def close(self):
"""Close the HTTP client."""
"""Close the HTTP client and CalDAV client."""
await self._client.aclose()
await self.calendar.close()
nextcloud_mcp_server/client/base.py
+4 -4
View File
@@ -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/calendar.py
+860 -770
View File
File diff suppressed because it is too large Load Diff
nextcloud_mcp_server/client/contacts.py
+3 -1
View File
@@ -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/cookbook.py
+250
View File
@@ -0,0 +1,250 @@
"""Client for Nextcloud Cookbook app operations."""
import logging
from typing import Any, Dict, List
from httpx import Timeout
from .base import BaseNextcloudClient
logger = logging.getLogger(__name__)
class CookbookClient(BaseNextcloudClient):
"""Client for Nextcloud Cookbook app operations."""
async def get_version(self) -> Dict[str, Any]:
"""Get Cookbook app and API version."""
response = await self._make_request("GET", "/apps/cookbook/api/version")
return response.json()
async def get_config(self) -> Dict[str, Any]:
"""Get current Cookbook app configuration."""
response = await self._make_request("GET", "/apps/cookbook/api/v1/config")
return response.json()
async def set_config(self, config: Dict[str, Any]) -> Dict[str, Any]:
"""Set Cookbook app configuration.
Args:
config: Configuration dictionary with fields like:
- folder: Recipe folder path
- update_interval: Auto-rescan interval in minutes
- print_image: Whether to print images with recipes
- visibleInfoBlocks: Visible info blocks configuration
Returns:
Response with status message
"""
response = await self._make_request(
"POST", "/apps/cookbook/api/v1/config", json=config
)
return response.json()
async def reindex(self) -> str:
"""Trigger a rescan of all recipes into the caching database.
Returns:
Success message
"""
response = await self._make_request("POST", "/apps/cookbook/api/v1/reindex")
return response.json()
async def list_recipes(self) -> List[Dict[str, Any]]:
"""Get all recipes in the database.
Returns:
List of recipe stubs with basic information
"""
response = await self._make_request("GET", "/apps/cookbook/api/v1/recipes")
return response.json()
async def get_recipe(self, recipe_id: int) -> Dict[str, Any]:
"""Get a single recipe by ID.
Args:
recipe_id: The recipe ID
Returns:
Full recipe data
"""
response = await self._make_request(
"GET", f"/apps/cookbook/api/v1/recipes/{recipe_id}"
)
return response.json()
async def create_recipe(self, recipe_data: Dict[str, Any]) -> int:
"""Create a new recipe.
Args:
recipe_data: Recipe data following schema.org/Recipe format.
Required: name
Optional: description, ingredients, instructions, etc.
Returns:
ID of the newly created recipe
"""
response = await self._make_request(
"POST", "/apps/cookbook/api/v1/recipes", json=recipe_data
)
return response.json()
async def update_recipe(self, recipe_id: int, recipe_data: Dict[str, Any]) -> int:
"""Update an existing recipe.
Args:
recipe_id: The recipe ID to update
recipe_data: Updated recipe data
Returns:
ID of the updated recipe
"""
response = await self._make_request(
"PUT", f"/apps/cookbook/api/v1/recipes/{recipe_id}", json=recipe_data
)
return response.json()
async def delete_recipe(self, recipe_id: int) -> str:
"""Delete a recipe.
Args:
recipe_id: The recipe ID to delete
Returns:
Success message
"""
response = await self._make_request(
"DELETE", f"/apps/cookbook/api/v1/recipes/{recipe_id}"
)
return response.json()
async def import_recipe(self, url: str) -> Dict[str, Any]:
"""Import a recipe from a URL using schema.org metadata.
Args:
url: URL of the recipe to import
Returns:
Full imported recipe data
"""
logger.info(f"Importing recipe from URL: {url}")
response = await self._make_request(
"POST",
"/apps/cookbook/api/v1/import",
json={"url": url},
timeout=Timeout(300.0),
)
return response.json()
async def get_recipe_image(self, recipe_id: int, size: str = "full") -> bytes:
"""Get the main image of a recipe.
Args:
recipe_id: The recipe ID
size: Image size - "full", "thumb" (250px), or "thumb16" (16px)
Returns:
Image bytes
"""
response = await self._make_request(
"GET",
f"/apps/cookbook/api/v1/recipes/{recipe_id}/image",
params={"size": size},
)
return response.content
async def search_recipes(self, query: str) -> List[Dict[str, Any]]:
"""Search for recipes by keywords, tags, and categories.
Args:
query: Search string (URL-encoded, space/comma separated)
Returns:
List of matching recipe stubs
"""
# URL encode the query
from urllib.parse import quote
encoded_query = quote(query)
response = await self._make_request(
"GET", f"/apps/cookbook/api/v1/search/{encoded_query}"
)
return response.json()
async def list_categories(self) -> List[Dict[str, Any]]:
"""Get all known categories.
Note: A category name of '*' indicates recipes with no category.
Returns:
List of categories with recipe counts
"""
response = await self._make_request("GET", "/apps/cookbook/api/v1/categories")
return response.json()
async def get_recipes_in_category(self, category: str) -> List[Dict[str, Any]]:
"""Get all recipes in a specific category.
Args:
category: Category name (use "_" for recipes with no category)
Returns:
List of recipe stubs in the category
"""
from urllib.parse import quote
encoded_category = quote(category)
response = await self._make_request(
"GET", f"/apps/cookbook/api/v1/category/{encoded_category}"
)
return response.json()
async def rename_category(self, old_name: str, new_name: str) -> str:
"""Rename a category.
Args:
old_name: Current category name
new_name: New category name
Returns:
New category name
"""
from urllib.parse import quote
encoded_old_name = quote(old_name)
response = await self._make_request(
"PUT",
f"/apps/cookbook/api/v1/category/{encoded_old_name}",
json={"name": new_name},
)
return response.json()
async def list_keywords(self) -> List[Dict[str, Any]]:
"""Get all known keywords/tags.
Returns:
List of keywords with recipe counts
"""
response = await self._make_request("GET", "/apps/cookbook/api/v1/keywords")
return response.json()
async def get_recipes_with_keywords(
self, keywords: List[str]
) -> List[Dict[str, Any]]:
"""Get all recipes associated with certain keywords.
Args:
keywords: List of keywords to filter by
Returns:
List of recipe stubs matching the keywords
"""
from urllib.parse import quote
# Join keywords with commas
keywords_str = ",".join(keywords)
encoded_keywords = quote(keywords_str)
response = await self._make_request(
"GET", f"/apps/cookbook/api/v1/tags/{encoded_keywords}"
)
return response.json()
nextcloud_mcp_server/client/deck.py
+22 -11
View File
@@ -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
+151
View File
@@ -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/notes.py
+6 -8
View File
@@ -1,7 +1,7 @@
"""Client for Nextcloud Notes app operations."""
import logging
from typing import Any, Dict, List, Optional
from typing import Any, AsyncIterator, Dict, Optional
from .base import BaseNextcloudClient
@@ -16,24 +16,22 @@ class NotesClient(BaseNextcloudClient):
response = await self._make_request("GET", "/apps/notes/api/v1/settings")
return response.json()
async def get_all_notes(self) -> List[Dict[str, Any]]:
"""Get all notes."""
notes = []
async def get_all_notes(self) -> AsyncIterator[Dict[str, Any]]:
"""Get all notes, yielding them one at a time."""
cursor = ""
while True:
response = await self._make_request(
"GET",
"/apps/notes/api/v1/notes",
params={"chunkSize": 50, "chunkCursor": cursor},
params={"chunkSize": 10, "chunkCursor": cursor},
)
notes.extend(response.json())
for note in response.json():
yield note
if "X-Notes-Chunk-Cursor" not in response.headers:
break
cursor = response.headers["X-Notes-Chunk-Cursor"]
return notes
async def get_note(self, note_id: int) -> Dict[str, Any]:
"""Get a specific note by ID."""
response = await self._make_request(
nextcloud_mcp_server/client/sharing.py
+208
View File
@@ -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
+223
View File
@@ -0,0 +1,223 @@
from typing import Dict, List, Optional
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/client/webdav.py
+376
View File
@@ -570,3 +570,379 @@ class WebDAVClient(BaseNextcloudClient):
f"Unexpected error copying resource from '{source_path}' to '{destination_path}': {e}"
)
raise e
async def search_files(
self,
scope: str = "",
where_conditions: Optional[str] = None,
properties: Optional[List[str]] = None,
order_by: Optional[List[Tuple[str, str]]] = None,
limit: Optional[int] = None,
) -> List[Dict[str, Any]]:
"""Search for files using WebDAV SEARCH method (RFC 5323).
Args:
scope: Directory path to search in (empty string for user root)
where_conditions: XML string for where clause conditions
properties: List of property names to retrieve (defaults to basic set)
order_by: List of (property, direction) tuples for sorting, e.g. [("getlastmodified", "descending")]
limit: Maximum number of results to return
Returns:
List of file/directory dictionaries with requested properties
"""
# Default properties if not specified
if properties is None:
properties = [
"displayname",
"getcontentlength",
"getcontenttype",
"getlastmodified",
"resourcetype",
"getetag",
]
# Build the SEARCH request XML
search_body = self._build_search_xml(
scope=scope,
where_conditions=where_conditions,
properties=properties,
order_by=order_by,
limit=limit,
)
# The SEARCH endpoint is at the dav root
search_path = "/remote.php/dav/"
headers = {"Content-Type": "text/xml", "OCS-APIRequest": "true"}
logger.debug(f"Searching files in scope: {scope}")
try:
response = await self._make_request(
"SEARCH", search_path, content=search_body, headers=headers
)
response.raise_for_status()
# Parse the XML response
results = self._parse_search_response(response.content, scope)
logger.debug(f"Search returned {len(results)} results")
return results
except HTTPStatusError as e:
logger.error(f"HTTP error during search: {e}")
raise e
except Exception as e:
logger.error(f"Unexpected error during search: {e}")
raise e
def _build_search_xml(
self,
scope: str,
where_conditions: Optional[str],
properties: List[str],
order_by: Optional[List[Tuple[str, str]]],
limit: Optional[int],
) -> str:
"""Build the XML body for a SEARCH request."""
# Construct the scope path
username = self.username
scope_path = f"/files/{username}"
if scope:
scope_path = f"{scope_path}/{scope.lstrip('/')}"
# Build property list
prop_xml = "\n".join([self._property_to_xml(prop) for prop in properties])
# Build where clause
where_xml = where_conditions if where_conditions else ""
# Build order by clause
orderby_xml = ""
if order_by:
order_elements = []
for prop, direction in order_by:
prop_element = self._property_to_xml(prop)
dir_element = (
"<d:ascending/>"
if direction.lower() == "ascending"
else "<d:descending/>"
)
order_elements.append(f"<d:order>{prop_element}{dir_element}</d:order>")
orderby_xml = "\n".join(order_elements)
else:
orderby_xml = ""
# Build limit clause
limit_xml = (
f"<d:limit><d:nresults>{limit}</d:nresults></d:limit>" if limit else ""
)
# Construct the full SEARCH XML
search_xml = f"""<?xml version="1.0" encoding="UTF-8"?>
<d:searchrequest xmlns:d="DAV:" xmlns:oc="http://owncloud.org/ns" xmlns:nc="http://nextcloud.org/ns">
<d:basicsearch>
<d:select>
<d:prop>
{prop_xml}
</d:prop>
</d:select>
<d:from>
<d:scope>
<d:href>{scope_path}</d:href>
<d:depth>infinity</d:depth>
</d:scope>
</d:from>
<d:where>
{where_xml}
</d:where>
<d:orderby>
{orderby_xml}
</d:orderby>
{limit_xml}
</d:basicsearch>
</d:searchrequest>"""
return search_xml
def _property_to_xml(self, prop: str) -> str:
"""Convert a property name to its XML element."""
# Handle properties with namespace prefixes
if prop.startswith("{"):
# Already a full namespace
namespace_end = prop.index("}")
namespace = prop[1:namespace_end]
local_name = prop[namespace_end + 1 :]
# Map namespace URIs to prefixes
ns_map = {
"DAV:": "d",
"http://owncloud.org/ns": "oc",
"http://nextcloud.org/ns": "nc",
}
prefix = ns_map.get(namespace, "d")
return f"<{prefix}:{local_name}/>"
else:
# Guess namespace based on common properties
if prop in [
"displayname",
"getcontentlength",
"getcontenttype",
"getlastmodified",
"resourcetype",
"getetag",
"quota-available-bytes",
"quota-used-bytes",
]:
return f"<d:{prop}/>"
elif prop in [
"fileid",
"size",
"permissions",
"favorite",
"tags",
"owner-id",
"owner-display-name",
"share-types",
"checksums",
"comments-count",
"comments-unread",
]:
return f"<oc:{prop}/>"
else:
# Assume nc namespace for newer properties
return f"<nc:{prop}/>"
def _parse_search_response(
self, xml_content: bytes, scope: str
) -> List[Dict[str, Any]]:
"""Parse the XML response from a SEARCH request."""
root = ET.fromstring(xml_content)
items = []
# Process each response element
responses = root.findall(".//{DAV:}response")
for response_elem in responses:
href = response_elem.find(".//{DAV:}href")
if href is None:
continue
# Extract file/directory path from href
href_text = href.text or ""
# Remove the /remote.php/dav/files/username/ prefix to get relative path
path_parts = href_text.split("/files/")
if len(path_parts) > 1:
# Get the path after username
path_after_user = "/".join(path_parts[1].split("/")[1:])
relative_path = path_after_user.rstrip("/")
else:
relative_path = href_text.rstrip("/").split("/")[-1]
# Get properties
propstat = response_elem.find(".//{DAV:}propstat")
if propstat is None:
continue
prop = propstat.find(".//{DAV:}prop")
if prop is None:
continue
# Build item dictionary
item = {"path": relative_path, "href": href_text}
# Extract all properties
for child in prop:
tag = child.tag
value = child.text
# Remove namespace from tag
if "}" in tag:
tag = tag.split("}", 1)[1]
# Handle special properties
if tag == "resourcetype":
item["is_directory"] = child.find(".//{DAV:}collection") is not None
elif tag == "getcontentlength":
item["size"] = int(value) if value else 0
elif tag == "displayname":
item["name"] = value
elif tag == "getcontenttype":
item["content_type"] = value
elif tag == "getlastmodified":
item["last_modified"] = value
elif tag == "getetag":
item["etag"] = value.strip('"') if value else None
elif tag == "fileid":
item["file_id"] = int(value) if value else None
elif tag == "favorite":
item["is_favorite"] = value == "1"
elif tag == "permissions":
item["permissions"] = value
elif tag == "size":
# oc:size includes folder sizes
item["total_size"] = int(value) if value else 0
else:
# Store other properties as-is
item[tag] = value
items.append(item)
return items
async def find_by_name(
self, pattern: str, scope: str = "", limit: Optional[int] = None
) -> List[Dict[str, Any]]:
"""Find files by name pattern using LIKE matching.
Args:
pattern: Name pattern to search for (supports % wildcard)
scope: Directory path to search in (empty string for user root)
limit: Maximum number of results to return
Returns:
List of matching files/directories
Examples:
# Find all .txt files
results = await find_by_name("%.txt")
# Find files starting with "report"
results = await find_by_name("report%")
"""
where_conditions = f"""
<d:like>
<d:prop>
<d:displayname/>
</d:prop>
<d:literal>{pattern}</d:literal>
</d:like>
"""
return await self.search_files(
scope=scope, where_conditions=where_conditions, limit=limit
)
async def find_by_type(
self, mime_type: str, scope: str = "", limit: Optional[int] = None
) -> List[Dict[str, Any]]:
"""Find files by MIME type.
Args:
mime_type: MIME type to search for (supports % wildcard, e.g., "image/%")
scope: Directory path to search in (empty string for user root)
limit: Maximum number of results to return
Returns:
List of matching files
Examples:
# Find all images
results = await find_by_type("image/%")
# Find all PDFs
results = await find_by_type("application/pdf")
"""
where_conditions = f"""
<d:like>
<d:prop>
<d:getcontenttype/>
</d:prop>
<d:literal>{mime_type}</d:literal>
</d:like>
"""
return await self.search_files(
scope=scope, where_conditions=where_conditions, limit=limit
)
async def list_favorites(
self, scope: str = "", limit: Optional[int] = None
) -> List[Dict[str, Any]]:
"""List all favorite files.
Args:
scope: Directory path to search in (empty string for user root)
limit: Maximum number of results to return
Returns:
List of favorite files/directories
Examples:
# List all favorites
results = await list_favorites()
# List favorites in a specific folder
results = await list_favorites(scope="Documents")
"""
# Use REPORT method for favorites as it's more efficient
# But we can also use SEARCH as fallback
where_conditions = """
<d:eq>
<d:prop>
<oc:favorite/>
</d:prop>
<d:literal>1</d:literal>
</d:eq>
"""
# Request favorite property
properties = [
"displayname",
"getcontentlength",
"getcontenttype",
"getlastmodified",
"resourcetype",
"getetag",
"fileid",
"favorite",
]
return await self.search_files(
scope=scope,
where_conditions=where_conditions,
properties=properties,
limit=limit,
)
nextcloud_mcp_server/config.py
+18 -2
View File
@@ -4,17 +4,18 @@ from typing import Optional
LOGGING_CONFIG = {
"version": 1,
"disable_existing_loggers": False,
"handlers": {
"default": {
"class": "logging.StreamHandler",
"formatter": "http",
}
},
},
"formatters": {
"http": {
"format": "%(levelname)s [%(asctime)s] %(name)s - %(message)s",
"datefmt": "%Y-%m-%d %H:%M:%S",
}
},
},
"loggers": {
"": {
@@ -31,6 +32,21 @@ LOGGING_CONFIG = {
"level": "INFO",
"propagate": False, # Prevent propagation to root logger
},
"uvicorn": {
"handlers": ["default"],
"level": "INFO",
"propagate": False,
},
"uvicorn.access": {
"handlers": ["default"],
"level": "INFO",
"propagate": False,
},
"uvicorn.error": {
"handlers": ["default"],
"level": "INFO",
"propagate": False,
},
},
}
nextcloud_mcp_server/context.py
+51
View File
@@ -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/controllers/notes_search.py
+4 -4
View File
@@ -1,13 +1,13 @@
"""Controller for notes search functionality."""
from typing import Any, Dict, List
from typing import Any, AsyncIterable, Dict, List
class NotesSearchController:
"""Handles notes search logic and scoring."""
def search_notes(
self, notes: List[Dict[str, Any]], query: str
async def search_notes(
self, notes: AsyncIterable[Dict[str, Any]], query: str
) -> List[Dict[str, Any]]:
"""
Search notes using token-based matching with relevance ranking.
@@ -21,7 +21,7 @@ class NotesSearchController:
return []
# Process and score each note
for note in notes:
async for note in notes:
title_tokens, content_tokens = self._process_note_content(note)
score = self._calculate_score(query_tokens, title_tokens, content_tokens)
nextcloud_mcp_server/models/__init__.py
+42 -40
View File
@@ -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,53 @@ 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,
CopyResourceResponse,
CreateDirectoryResponse,
DeleteResourceResponse,
DirectoryListing,
FileInfo,
MoveResourceResponse,
ReadFileResponse,
SearchFilesResponse,
WriteFileResponse,
)
__all__ = [
@@ -137,4 +136,7 @@ __all__ = [
"WriteFileResponse",
"CreateDirectoryResponse",
"DeleteResourceResponse",
"MoveResourceResponse",
"CopyResourceResponse",
"SearchFilesResponse",
]
nextcloud_mcp_server/models/calendar.py
+68
View File
@@ -180,3 +180,71 @@ class ManageCalendarResponse(BaseResponse):
None, description="List of calendars (for list action)"
)
message: str = Field(description="Success message")
# ============= Todo/Task Models =============
class Todo(BaseModel):
"""Model for a CalDAV todo/task (VTODO)."""
uid: str = Field(description="Todo UID")
summary: str = Field(description="Todo summary/title")
description: str = Field(default="", description="Todo description")
status: str = Field(
default="NEEDS-ACTION",
description="Todo status: NEEDS-ACTION, IN-PROCESS, COMPLETED, CANCELLED",
)
priority: int = Field(
default=0, description="Todo priority (0=undefined, 1=highest, 9=lowest)"
)
percent_complete: int = Field(default=0, description="Percentage complete (0-100)")
due: Optional[str] = Field(None, description="Due date/time (ISO format)")
dtstart: Optional[str] = Field(None, description="Start date/time (ISO format)")
completed: Optional[str] = Field(
None, description="Completion timestamp (ISO format)"
)
categories: str = Field(default="", description="Comma-separated categories")
href: str = Field(default="", description="CalDAV href")
etag: str = Field(default="", description="ETag for versioning")
calendar_name: Optional[str] = Field(
None, description="Calendar containing this todo"
)
calendar_display_name: Optional[str] = Field(
None, description="Display name of calendar containing this todo"
)
class ListTodosResponse(BaseResponse):
"""Response model for listing todos."""
todos: List[Todo] = Field(description="List of todos/tasks")
calendar_name: Optional[str] = Field(
None, description="Calendar name (if filtered to one calendar)"
)
total_count: int = Field(description="Total number of todos found")
class CreateTodoResponse(BaseResponse):
"""Response model for todo creation."""
todo: Todo = Field(description="The created todo")
calendar_name: str = Field(
description="Name of the calendar the todo was created in"
)
class UpdateTodoResponse(BaseResponse):
"""Response model for todo updates."""
todo: Todo = Field(description="The updated todo")
calendar_name: str = Field(description="Name of the calendar the todo belongs to")
class DeleteTodoResponse(StatusResponse):
"""Response model for todo deletion."""
deleted_uid: str = Field(description="UID of the deleted todo")
calendar_name: str = Field(
description="Name of the calendar the todo was deleted from"
)
nextcloud_mcp_server/models/cookbook.py
+220
View File
@@ -0,0 +1,220 @@
"""Pydantic models for Cookbook app responses."""
from typing import List, Optional, Union
from pydantic import BaseModel, Field
from .base import BaseResponse, IdResponse, StatusResponse
class Nutrition(BaseModel):
"""Nutrition information following schema.org/NutritionInformation."""
type: str = Field(
default="NutritionInformation",
alias="@type",
description="Schema.org object type",
)
calories: Optional[str] = Field(None, description="Calories (e.g., '650 kcal')")
carbohydrateContent: Optional[str] = Field(
None, description="Carbohydrates (e.g., '300 g')"
)
cholesterolContent: Optional[str] = Field(
None, description="Cholesterol (e.g., '10 g')"
)
fatContent: Optional[str] = Field(None, description="Fat (e.g., '45 g')")
fiberContent: Optional[str] = Field(None, description="Fiber (e.g., '50 g')")
proteinContent: Optional[str] = Field(None, description="Protein (e.g., '80 g')")
saturatedFatContent: Optional[str] = Field(
None, description="Saturated fat (e.g., '5 g')"
)
servingSize: Optional[str] = Field(
None, description="Serving size description (e.g., 'One plate')"
)
sodiumContent: Optional[str] = Field(None, description="Sodium (e.g., '10 mg')")
sugarContent: Optional[str] = Field(None, description="Sugar (e.g., '5 g')")
transFatContent: Optional[str] = Field(None, description="Trans fat (e.g., '10 g')")
unsaturatedFatContent: Optional[str] = Field(
None, description="Unsaturated fat (e.g., '40 g')"
)
class Config:
populate_by_name = True
class RecipeStub(BaseModel):
"""Stub of a recipe with basic information."""
id: str = Field(description="Recipe ID as string")
recipe_id: int = Field(description="Recipe ID as integer (deprecated)")
name: str = Field(description="Recipe name")
keywords: Optional[str] = Field(default="", description="Comma-separated keywords")
dateCreated: str = Field(description="Creation date (ISO8601)")
dateModified: Optional[str] = Field(
None, description="Last modified date (ISO8601)"
)
imageUrl: str = Field(default="", description="URL of the recipe image")
imagePlaceholderUrl: str = Field(default="", description="URL of placeholder image")
class Recipe(BaseModel):
"""Full recipe following schema.org/Recipe specification."""
type: str = Field(default="Recipe", alias="@type", description="Schema.org type")
id: Optional[str] = Field(None, description="Recipe ID")
name: str = Field(description="Recipe name")
description: str = Field(default="", description="Recipe description")
url: str = Field(default="", description="Original recipe URL")
image: str = Field(default="", description="URL of original recipe image")
imageUrl: Optional[str] = Field(
None, description="URL of the recipe image in Nextcloud"
)
imagePlaceholderUrl: Optional[str] = Field(
None, description="URL of placeholder image"
)
keywords: str = Field(default="", description="Comma-separated keywords")
dateCreated: Optional[str] = Field(None, description="Creation date (ISO8601)")
dateModified: Optional[str] = Field(
None, description="Last modified date (ISO8601)"
)
prepTime: Optional[str] = Field(None, description="Preparation time (ISO8601)")
cookTime: Optional[str] = Field(None, description="Cooking time (ISO8601)")
totalTime: Optional[str] = Field(None, description="Total time (ISO8601)")
recipeYield: Union[int, str] = Field(default=1, description="Number of servings")
recipeCategory: str = Field(default="", description="Recipe category")
tool: List[str] = Field(default_factory=list, description="Required tools")
recipeIngredient: List[str] = Field(
default_factory=list, description="List of ingredients"
)
recipeInstructions: List[str] = Field(
default_factory=list, description="Cooking instructions"
)
nutrition: Optional[Nutrition] = Field(None, description="Nutrition information")
class Config:
populate_by_name = True
extra = "allow" # Allow additional schema.org fields
class Category(BaseModel):
"""A recipe category."""
name: str = Field(description="Category name")
recipe_count: int = Field(description="Number of recipes in category")
class Keyword(BaseModel):
"""A recipe keyword/tag."""
name: str = Field(description="Keyword name")
recipe_count: int = Field(description="Number of recipes with this keyword")
class VisibleInfoBlocks(BaseModel):
"""Configuration for visible information blocks in the UI."""
preparation_time: Optional[bool] = Field(
None, alias="preparation-time", description="Show preparation time"
)
cooking_time: Optional[bool] = Field(
None, alias="cooking-time", description="Show cooking time"
)
total_time: Optional[bool] = Field(
None, alias="total-time", description="Show total time"
)
nutrition_information: Optional[bool] = Field(
None, alias="nutrition-information", description="Show nutrition info"
)
tools: Optional[bool] = Field(None, description="Show tools list")
class Config:
populate_by_name = True
class CookbookConfig(BaseModel):
"""Cookbook app configuration."""
folder: Optional[str] = Field(None, description="Recipe folder path")
update_interval: Optional[int] = Field(
None, description="Auto-rescan interval in minutes"
)
print_image: Optional[bool] = Field(None, description="Print images with recipes")
visibleInfoBlocks: Optional[VisibleInfoBlocks] = Field(
None, description="Visible info blocks configuration"
)
class APIVersion(BaseModel):
"""API version information."""
epoch: int = Field(description="API epoch")
major: int = Field(description="Major version")
minor: int = Field(description="Minor version")
class Version(BaseModel):
"""Version information for Cookbook app and API."""
cookbook_version: List[int] = Field(description="Cookbook app version")
api_version: APIVersion = Field(description="API version")
# Response models for MCP tools
class ImportRecipeResponse(BaseResponse):
"""Response model for recipe import."""
recipe: Recipe = Field(description="The imported recipe")
recipe_id: str = Field(description="ID of the imported recipe")
class CreateRecipeResponse(IdResponse):
"""Response model for recipe creation."""
pass
class UpdateRecipeResponse(IdResponse):
"""Response model for recipe update."""
pass
class DeleteRecipeResponse(StatusResponse):
"""Response model for recipe deletion."""
deleted_id: int = Field(description="ID of deleted recipe")
class ListRecipesResponse(BaseResponse):
"""Response model for listing recipes."""
recipes: List[RecipeStub] = Field(description="List of recipe stubs")
total_count: int = Field(description="Total number of recipes")
class SearchRecipesResponse(BaseResponse):
"""Response model for recipe search."""
recipes: List[RecipeStub] = Field(description="Matching recipes")
query: str = Field(description="Search query used")
total_found: int = Field(description="Number of recipes found")
class ListCategoriesResponse(BaseResponse):
"""Response model for listing categories."""
categories: List[Category] = Field(description="List of categories")
class ListKeywordsResponse(BaseResponse):
"""Response model for listing keywords."""
keywords: List[Keyword] = Field(description="List of keywords")
class ReindexResponse(StatusResponse):
"""Response model for reindex operation."""
pass
nextcloud_mcp_server/models/deck.py
+1 -1
View File
@@ -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
+41
View File
@@ -0,0 +1,41 @@
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/models/webdav.py
+13
View File
@@ -22,6 +22,8 @@ class FileInfo(BaseModel):
None, description="Last modification time (ISO format)"
)
etag: Optional[str] = Field(None, description="ETag for versioning")
file_id: Optional[int] = Field(None, description="Nextcloud file ID")
is_favorite: Optional[bool] = Field(None, description="Whether file is favorited")
@property
def last_modified_datetime(self) -> Optional[datetime]:
@@ -106,3 +108,14 @@ class CopyResourceResponse(StatusResponse):
overwrite: bool = Field(
description="Whether the destination was overwritten if it existed"
)
class SearchFilesResponse(BaseResponse):
"""Response model for WebDAV search operations."""
results: List[FileInfo] = Field(description="Search results")
total_found: int = Field(description="Total number of files found")
scope: str = Field(description="The scope/path that was searched")
filters_applied: Optional[dict] = Field(
None, description="Filters that were applied to the search"
)
nextcloud_mcp_server/server/__init__.py
+6 -2
View File
@@ -1,15 +1,19 @@
from .calendar import configure_calendar_tools
from .contacts import configure_contacts_tools
from .cookbook import configure_cookbook_tools
from .deck import configure_deck_tools
from .notes import configure_notes_tools
from .sharing import configure_sharing_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
__all__ = [
"configure_calendar_tools",
"configure_contacts_tools",
"configure_cookbook_tools",
"configure_deck_tools",
"configure_notes_tools",
"configure_sharing_tools",
"configure_tables_tools",
"configure_webdav_tools",
]
nextcloud_mcp_server/server/calendar.py
+220 -12
View File
@@ -4,10 +4,12 @@ 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.calendar import (
Calendar,
ListCalendarsResponse,
ListTodosResponse,
Todo,
)
logger = logging.getLogger(__name__)
@@ -18,7 +20,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 +76,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 +135,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 +209,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 +242,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 +292,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 +334,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 +368,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 +437,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 +538,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 +760,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()
@@ -799,3 +801,209 @@ def configure_calendar_tools(mcp: FastMCP):
else:
raise ValueError("Action must be 'create', 'delete', 'update', or 'list'")
# ============= Todo/Task Tools =============
@mcp.tool()
async def nc_calendar_list_todos(
calendar_name: str,
ctx: Context,
status: Optional[str] = None,
min_priority: Optional[int] = None,
categories: Optional[str] = None,
summary_contains: Optional[str] = None,
) -> ListTodosResponse:
"""List todos/tasks in a calendar with optional filtering.
Args:
calendar_name: Name of the calendar to list todos from
ctx: MCP context
status: Filter by status (NEEDS-ACTION, IN-PROCESS, COMPLETED, CANCELLED)
min_priority: Filter by minimum priority (1=highest, 9=lowest)
categories: Filter by categories (comma-separated, e.g., "work,urgent")
summary_contains: Filter todos where summary contains this text
Returns:
List of todos matching the filters
"""
client = get_client(ctx)
# Build filters dictionary
filters = {}
if status is not None:
filters["status"] = status
if min_priority is not None:
filters["min_priority"] = min_priority
if categories is not None:
filters["categories"] = [cat.strip() for cat in categories.split(",")]
if summary_contains is not None:
filters["summary_contains"] = summary_contains
todos_data = await client.calendar.list_todos(
calendar_name, filters if filters else None
)
todos = [Todo(**todo_data) for todo_data in todos_data]
return ListTodosResponse(
todos=todos, calendar_name=calendar_name, total_count=len(todos)
)
@mcp.tool()
async def nc_calendar_create_todo(
calendar_name: str,
summary: str,
ctx: Context,
description: str = "",
status: str = "NEEDS-ACTION",
priority: int = 0,
due: str = "",
dtstart: str = "",
categories: str = "",
):
"""Create a new todo/task in a calendar.
Args:
calendar_name: Name of the calendar to create the todo in
summary: Todo title/summary
ctx: MCP context
description: Detailed description of the todo
status: Todo status (NEEDS-ACTION, IN-PROCESS, COMPLETED, CANCELLED)
priority: Priority (0=undefined, 1=highest, 9=lowest)
due: Due date/time (ISO format, e.g., "2025-01-15T14:00:00")
dtstart: Start date/time (ISO format)
categories: Comma-separated categories (e.g., "work,urgent")
Returns:
Dict with todo creation result
"""
client = get_client(ctx)
todo_data = {
"summary": summary,
"description": description,
"status": status,
"priority": priority,
"due": due,
"dtstart": dtstart,
"categories": categories,
}
return await client.calendar.create_todo(calendar_name, todo_data)
@mcp.tool()
async def nc_calendar_update_todo(
calendar_name: str,
todo_uid: str,
ctx: Context,
summary: Optional[str] = None,
description: Optional[str] = None,
status: Optional[str] = None,
priority: Optional[int] = None,
percent_complete: Optional[int] = None,
due: Optional[str] = None,
dtstart: Optional[str] = None,
completed: Optional[str] = None,
categories: Optional[str] = None,
):
"""Update an existing todo/task.
Args:
calendar_name: Name of the calendar containing the todo
todo_uid: UID of the todo to update
ctx: MCP context
summary: New summary/title
description: New description
status: New status (NEEDS-ACTION, IN-PROCESS, COMPLETED, CANCELLED)
priority: New priority (0-9)
percent_complete: New completion percentage (0-100)
due: New due date/time (ISO format)
dtstart: New start date/time (ISO format)
completed: Completion timestamp (ISO format)
categories: New categories (comma-separated)
Returns:
Dict with todo update result
"""
client = get_client(ctx)
# Build update data with only non-None values
todo_data = {}
if summary is not None:
todo_data["summary"] = summary
if description is not None:
todo_data["description"] = description
if status is not None:
todo_data["status"] = status
if priority is not None:
todo_data["priority"] = priority
if percent_complete is not None:
todo_data["percent_complete"] = percent_complete
if due is not None:
todo_data["due"] = due
if dtstart is not None:
todo_data["dtstart"] = dtstart
if completed is not None:
todo_data["completed"] = completed
if categories is not None:
todo_data["categories"] = categories
return await client.calendar.update_todo(calendar_name, todo_uid, todo_data)
@mcp.tool()
async def nc_calendar_delete_todo(
calendar_name: str,
todo_uid: str,
ctx: Context,
):
"""Delete a todo/task from a calendar.
Args:
calendar_name: Name of the calendar containing the todo
todo_uid: UID of the todo to delete
ctx: MCP context
Returns:
Dict with deletion status
"""
client = get_client(ctx)
return await client.calendar.delete_todo(calendar_name, todo_uid)
@mcp.tool()
async def nc_calendar_search_todos(
ctx: Context,
status: Optional[str] = None,
min_priority: Optional[int] = None,
categories: Optional[str] = None,
summary_contains: Optional[str] = None,
):
"""Search todos across all calendars with optional filtering.
Args:
ctx: MCP context
status: Filter by status (NEEDS-ACTION, IN-PROCESS, COMPLETED, CANCELLED)
min_priority: Filter by minimum priority (1=highest, 9=lowest)
categories: Filter by categories (comma-separated, e.g., "work,urgent")
summary_contains: Filter todos where summary contains this text
Returns:
List of todos matching the filters from all calendars
"""
client = get_client(ctx)
# Build filters dictionary
filters = {}
if status is not None:
filters["status"] = status
if min_priority is not None:
filters["min_priority"] = min_priority
if categories is not None:
filters["categories"] = [cat.strip() for cat in categories.split(",")]
if summary_contains is not None:
filters["summary_contains"] = summary_contains
todos_data = await client.calendar.search_todos_across_calendars(
filters if filters else None
)
todos = [Todo(**todo_data) for todo_data in todos_data]
return ListTodosResponse(todos=todos, total_count=len(todos))
nextcloud_mcp_server/server/contacts.py
+8 -8
View File
@@ -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/cookbook.py
+594
View File
@@ -0,0 +1,594 @@
import logging
from httpx import HTTPStatusError, RequestError
from mcp.server.fastmcp import Context, FastMCP
from mcp.shared.exceptions import McpError
from mcp.types import ErrorData
from nextcloud_mcp_server.context import get_client
from nextcloud_mcp_server.models.cookbook import (
Category,
CookbookConfig,
CreateRecipeResponse,
DeleteRecipeResponse,
ImportRecipeResponse,
Keyword,
ListCategoriesResponse,
ListKeywordsResponse,
ListRecipesResponse,
Recipe,
RecipeStub,
ReindexResponse,
SearchRecipesResponse,
UpdateRecipeResponse,
Version,
)
logger = logging.getLogger(__name__)
def configure_cookbook_tools(mcp: FastMCP):
@mcp.resource("cookbook://version")
async def cookbook_get_version():
"""Get the Cookbook app and API version"""
ctx: Context = mcp.get_context()
client = get_client(ctx)
version_data = await client.cookbook.get_version()
return Version(**version_data)
@mcp.resource("cookbook://config")
async def cookbook_get_config():
"""Get the Cookbook app configuration"""
ctx: Context = mcp.get_context()
client = get_client(ctx)
config_data = await client.cookbook.get_config()
return CookbookConfig(**config_data)
@mcp.resource("nc://Cookbook/{recipe_id}")
async def nc_cookbook_get_recipe_resource(recipe_id: int):
"""Get a recipe by ID using resource URI"""
ctx: Context = mcp.get_context()
client = get_client(ctx)
try:
recipe_data = await client.cookbook.get_recipe(recipe_id)
return Recipe(**recipe_data)
except HTTPStatusError as e:
if e.response.status_code == 404:
raise McpError(
ErrorData(code=-1, message=f"Recipe {recipe_id} not found")
)
elif e.response.status_code == 403:
raise McpError(
ErrorData(code=-1, message=f"Access denied to recipe {recipe_id}")
)
else:
raise McpError(
ErrorData(
code=-1,
message=f"Failed to retrieve recipe {recipe_id}: {e.response.reason_phrase}",
)
)
@mcp.tool()
async def nc_cookbook_import_recipe(url: str, ctx: Context) -> ImportRecipeResponse:
"""Import a recipe from a URL using schema.org metadata.
This extracts recipe data from websites that use schema.org Recipe markup.
Many popular recipe sites support this standard."""
client = get_client(ctx)
try:
recipe_data = await client.cookbook.import_recipe(url)
recipe = Recipe(**recipe_data)
return ImportRecipeResponse(
recipe=recipe,
recipe_id=recipe.id or "unknown",
)
except RequestError as e:
# RequestError can have empty str() - get details from exception attributes
error_detail = (
str(e)
or f"{type(e).__name__}: {getattr(e, '__cause__', 'unknown cause')}"
)
raise McpError(
ErrorData(
code=-1,
message=f"Network error importing recipe from {url}: {error_detail}",
)
)
except HTTPStatusError as e:
if e.response.status_code == 400:
raise McpError(
ErrorData(
code=-1,
message=f"Invalid URL or missing 'url' field: {url}",
)
)
elif e.response.status_code == 409:
raise McpError(
ErrorData(
code=-1,
message="A recipe with this name already exists. Import aborted.",
)
)
elif e.response.status_code == 403:
raise McpError(
ErrorData(
code=-1,
message="Access denied: insufficient permissions to import recipes",
)
)
else:
raise McpError(
ErrorData(
code=-1,
message=f"Failed to import recipe from {url}: server error ({e.response.status_code})",
)
)
@mcp.tool()
async def nc_cookbook_list_recipes(ctx: Context) -> ListRecipesResponse:
"""Get all recipes in the database"""
client = get_client(ctx)
try:
recipes_data = await client.cookbook.list_recipes()
recipes = [RecipeStub(**r) for r in recipes_data]
return ListRecipesResponse(recipes=recipes, total_count=len(recipes))
except HTTPStatusError as e:
if e.response.status_code == 403:
raise McpError(
ErrorData(
code=-1,
message="Access denied: insufficient permissions to list recipes",
)
)
else:
raise McpError(
ErrorData(
code=-1,
message=f"Failed to list recipes: server error ({e.response.status_code})",
)
)
@mcp.tool()
async def nc_cookbook_get_recipe(recipe_id: int, ctx: Context) -> Recipe:
"""Get a specific recipe by its ID"""
client = get_client(ctx)
try:
recipe_data = await client.cookbook.get_recipe(recipe_id)
return Recipe(**recipe_data)
except HTTPStatusError as e:
if e.response.status_code == 404:
raise McpError(
ErrorData(code=-1, message=f"Recipe {recipe_id} not found")
)
elif e.response.status_code == 403:
raise McpError(
ErrorData(code=-1, message=f"Access denied to recipe {recipe_id}")
)
else:
raise McpError(
ErrorData(
code=-1,
message=f"Failed to retrieve recipe {recipe_id}: {e.response.reason_phrase}",
)
)
@mcp.tool()
async def nc_cookbook_create_recipe(
name: str,
description: str | None = None,
ingredients: list[str] | None = None,
instructions: list[str] | None = None,
url: str | None = None,
prep_time: str | None = None,
cook_time: str | None = None,
total_time: str | None = None,
recipe_yield: int | None = None,
category: str | None = None,
keywords: str | None = None,
ctx: Context = None,
) -> CreateRecipeResponse:
"""Create a new recipe.
Required: name
Optional: All other recipe fields following schema.org/Recipe format.
Times should be in ISO8601 duration format (e.g., 'PT30M' for 30 minutes)."""
client = get_client(ctx)
recipe_data = {"name": name}
if description:
recipe_data["description"] = description
if ingredients:
recipe_data["recipeIngredient"] = ingredients
if instructions:
recipe_data["recipeInstructions"] = instructions
if url:
recipe_data["url"] = url
if prep_time:
recipe_data["prepTime"] = prep_time
if cook_time:
recipe_data["cookTime"] = cook_time
if total_time:
recipe_data["totalTime"] = total_time
if recipe_yield:
recipe_data["recipeYield"] = recipe_yield
if category:
recipe_data["recipeCategory"] = category
if keywords:
recipe_data["keywords"] = keywords
try:
recipe_id = await client.cookbook.create_recipe(recipe_data)
return CreateRecipeResponse(id=recipe_id)
except HTTPStatusError as e:
if e.response.status_code == 409:
raise McpError(
ErrorData(
code=-1,
message=f"A recipe with name '{name}' already exists",
)
)
elif e.response.status_code == 422:
raise McpError(
ErrorData(
code=-1,
message="Recipe name is required and cannot be empty",
)
)
elif e.response.status_code == 403:
raise McpError(
ErrorData(
code=-1,
message="Access denied: insufficient permissions to create recipes",
)
)
else:
raise McpError(
ErrorData(
code=-1,
message=f"Failed to create recipe: server error ({e.response.status_code})",
)
)
@mcp.tool()
async def nc_cookbook_update_recipe(
recipe_id: int,
name: str | None = None,
description: str | None = None,
ingredients: list[str] | None = None,
instructions: list[str] | None = None,
url: str | None = None,
prep_time: str | None = None,
cook_time: str | None = None,
total_time: str | None = None,
recipe_yield: int | None = None,
category: str | None = None,
keywords: str | None = None,
ctx: Context = None,
) -> UpdateRecipeResponse:
"""Update an existing recipe.
Provide only the fields you want to update. Unspecified fields remain unchanged."""
client = get_client(ctx)
# First get the current recipe
try:
current_recipe = await client.cookbook.get_recipe(recipe_id)
except HTTPStatusError as e:
if e.response.status_code == 404:
raise McpError(
ErrorData(code=-1, message=f"Recipe {recipe_id} not found")
)
else:
raise McpError(
ErrorData(
code=-1,
message=f"Failed to fetch recipe {recipe_id}: {e.response.reason_phrase}",
)
)
# Update only specified fields
recipe_data = current_recipe.copy()
if name is not None:
recipe_data["name"] = name
if description is not None:
recipe_data["description"] = description
if ingredients is not None:
recipe_data["recipeIngredient"] = ingredients
if instructions is not None:
recipe_data["recipeInstructions"] = instructions
if url is not None:
recipe_data["url"] = url
if prep_time is not None:
recipe_data["prepTime"] = prep_time
if cook_time is not None:
recipe_data["cookTime"] = cook_time
if total_time is not None:
recipe_data["totalTime"] = total_time
if recipe_yield is not None:
recipe_data["recipeYield"] = recipe_yield
if category is not None:
recipe_data["recipeCategory"] = category
if keywords is not None:
recipe_data["keywords"] = keywords
try:
updated_id = await client.cookbook.update_recipe(recipe_id, recipe_data)
return UpdateRecipeResponse(id=updated_id)
except HTTPStatusError as e:
if e.response.status_code == 422:
raise McpError(
ErrorData(
code=-1,
message="Recipe name is required and cannot be empty",
)
)
elif e.response.status_code == 403:
raise McpError(
ErrorData(
code=-1,
message=f"Access denied: insufficient permissions to update recipe {recipe_id}",
)
)
else:
raise McpError(
ErrorData(
code=-1,
message=f"Failed to update recipe {recipe_id}: server error ({e.response.status_code})",
)
)
@mcp.tool()
async def nc_cookbook_delete_recipe(
recipe_id: int, ctx: Context
) -> DeleteRecipeResponse:
"""Delete a recipe permanently"""
logger.info("Deleting recipe %s", recipe_id)
client = get_client(ctx)
try:
message = await client.cookbook.delete_recipe(recipe_id)
return DeleteRecipeResponse(
status_code=200,
message=message,
deleted_id=recipe_id,
)
except HTTPStatusError as e:
if e.response.status_code == 404:
raise McpError(
ErrorData(code=-1, message=f"Recipe {recipe_id} not found")
)
elif e.response.status_code == 403:
raise McpError(
ErrorData(
code=-1,
message=f"Access denied: insufficient permissions to delete recipe {recipe_id}",
)
)
else:
raise McpError(
ErrorData(
code=-1,
message=f"Failed to delete recipe {recipe_id}: server error ({e.response.status_code})",
)
)
@mcp.tool()
async def nc_cookbook_search_recipes(
query: str, ctx: Context
) -> SearchRecipesResponse:
"""Search for recipes by keywords, tags, and categories"""
client = get_client(ctx)
try:
recipes_data = await client.cookbook.search_recipes(query)
recipes = [RecipeStub(**r) for r in recipes_data]
return SearchRecipesResponse(
recipes=recipes, query=query, total_found=len(recipes)
)
except HTTPStatusError as e:
if e.response.status_code == 403:
raise McpError(
ErrorData(
code=-1,
message="Access denied: insufficient permissions to search recipes",
)
)
elif e.response.status_code == 500:
raise McpError(
ErrorData(
code=-1,
message="Search failed: server error",
)
)
else:
raise McpError(
ErrorData(
code=-1,
message=f"Search failed: server error ({e.response.status_code})",
)
)
@mcp.tool()
async def nc_cookbook_list_categories(ctx: Context) -> ListCategoriesResponse:
"""Get all known categories.
Note: A category name of '*' indicates recipes with no category."""
client = get_client(ctx)
try:
categories_data = await client.cookbook.list_categories()
categories = [Category(**c) for c in categories_data]
return ListCategoriesResponse(categories=categories)
except HTTPStatusError as e:
if e.response.status_code == 403:
raise McpError(
ErrorData(
code=-1,
message="Access denied: insufficient permissions to list categories",
)
)
else:
raise McpError(
ErrorData(
code=-1,
message=f"Failed to list categories: server error ({e.response.status_code})",
)
)
@mcp.tool()
async def nc_cookbook_get_recipes_in_category(
category: str, ctx: Context
) -> ListRecipesResponse:
"""Get all recipes in a specific category.
Use '_' as the category name to get recipes with no category."""
client = get_client(ctx)
try:
recipes_data = await client.cookbook.get_recipes_in_category(category)
recipes = [RecipeStub(**r) for r in recipes_data]
return ListRecipesResponse(recipes=recipes, total_count=len(recipes))
except HTTPStatusError as e:
if e.response.status_code == 403:
raise McpError(
ErrorData(
code=-1,
message="Access denied: insufficient permissions to access recipes",
)
)
elif e.response.status_code == 500:
raise McpError(
ErrorData(
code=-1,
message=f"Could not find category '{category}'",
)
)
else:
raise McpError(
ErrorData(
code=-1,
message=f"Failed to get recipes in category: server error ({e.response.status_code})",
)
)
@mcp.tool()
async def nc_cookbook_list_keywords(ctx: Context) -> ListKeywordsResponse:
"""Get all known keywords/tags"""
client = get_client(ctx)
try:
keywords_data = await client.cookbook.list_keywords()
keywords = [Keyword(**k) for k in keywords_data]
return ListKeywordsResponse(keywords=keywords)
except HTTPStatusError as e:
if e.response.status_code == 403:
raise McpError(
ErrorData(
code=-1,
message="Access denied: insufficient permissions to list keywords",
)
)
else:
raise McpError(
ErrorData(
code=-1,
message=f"Failed to list keywords: server error ({e.response.status_code})",
)
)
@mcp.tool()
async def nc_cookbook_get_recipes_with_keywords(
keywords: list[str], ctx: Context
) -> ListRecipesResponse:
"""Get all recipes that have specific keywords/tags"""
client = get_client(ctx)
try:
recipes_data = await client.cookbook.get_recipes_with_keywords(keywords)
recipes = [RecipeStub(**r) for r in recipes_data]
return ListRecipesResponse(recipes=recipes, total_count=len(recipes))
except HTTPStatusError as e:
if e.response.status_code == 403:
raise McpError(
ErrorData(
code=-1,
message="Access denied: insufficient permissions to access recipes",
)
)
elif e.response.status_code == 500:
raise McpError(
ErrorData(
code=-1,
message="Failed to get recipes with keywords: server error",
)
)
else:
raise McpError(
ErrorData(
code=-1,
message=f"Failed to get recipes with keywords: server error ({e.response.status_code})",
)
)
@mcp.tool()
async def nc_cookbook_set_config(
folder: str | None = None,
update_interval: int | None = None,
print_image: bool | None = None,
ctx: Context = None,
) -> ReindexResponse:
"""Set Cookbook app configuration.
Args:
folder: Recipe folder path in user's files
update_interval: Automatic rescan interval in minutes
print_image: Whether to print images with recipes"""
client = get_client(ctx)
config_data = {}
if folder is not None:
config_data["folder"] = folder
if update_interval is not None:
config_data["update_interval"] = update_interval
if print_image is not None:
config_data["print_image"] = print_image
try:
result = await client.cookbook.set_config(config_data)
return ReindexResponse(status_code=200, message=str(result))
except HTTPStatusError as e:
if e.response.status_code == 403:
raise McpError(
ErrorData(
code=-1,
message="Access denied: insufficient permissions to set configuration",
)
)
else:
raise McpError(
ErrorData(
code=-1,
message=f"Failed to set configuration: server error ({e.response.status_code})",
)
)
@mcp.tool()
async def nc_cookbook_reindex(ctx: Context) -> ReindexResponse:
"""Trigger a rescan of all recipes into the caching database.
This rebuilds the search index and should be used after manual file changes."""
client = get_client(ctx)
try:
message = await client.cookbook.reindex()
return ReindexResponse(status_code=200, message=message)
except HTTPStatusError as e:
if e.response.status_code == 403:
raise McpError(
ErrorData(
code=-1,
message="Access denied: insufficient permissions to reindex",
)
)
else:
raise McpError(
ErrorData(
code=-1,
message=f"Failed to reindex: server error ({e.response.status_code})",
)
)
nextcloud_mcp_server/server/deck.py
+41 -41
View File
@@ -3,19 +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 (
CardOperationResponse,
CreateBoardResponse,
CreateCardResponse,
CreateLabelResponse,
CreateStackResponse,
DeckBoard,
DeckStack,
DeckCard,
DeckLabel,
CreateBoardResponse,
CreateStackResponse,
StackOperationResponse,
CreateCardResponse,
CardOperationResponse,
CreateLabelResponse,
DeckStack,
LabelOperationResponse,
StackOperationResponse,
)
logger = logging.getLogger(__name__)
@@ -30,7 +30,7 @@ def configure_deck_tools(mcp: FastMCP):
"""List all Nextcloud Deck boards"""
ctx: Context = mcp.get_context()
await ctx.warning("This message is deprecated, use the deck_get_board instead")
client: NextcloudClient = ctx.request_context.lifespan_context.client
client = get_client(ctx)
boards = await client.deck.get_boards()
return [board.model_dump() for board in boards]
@@ -41,7 +41,7 @@ def configure_deck_tools(mcp: FastMCP):
await ctx.warning(
"This resource is deprecated, use the deck_get_board tool instead"
)
client: NextcloudClient = ctx.request_context.lifespan_context.client
client = get_client(ctx)
board = await client.deck.get_board(board_id)
return board.model_dump()
@@ -52,7 +52,7 @@ def configure_deck_tools(mcp: FastMCP):
await ctx.warning(
"This resource is deprecated, use the deck_get_stacks tool instead"
)
client: NextcloudClient = ctx.request_context.lifespan_context.client
client = get_client(ctx)
stacks = await client.deck.get_stacks(board_id)
return [stack.model_dump() for stack in stacks]
@@ -63,7 +63,7 @@ def configure_deck_tools(mcp: FastMCP):
await ctx.warning(
"This resource is deprecated, use the deck_get_stack tool instead"
)
client: NextcloudClient = ctx.request_context.lifespan_context.client
client = get_client(ctx)
stack = await client.deck.get_stack(board_id, stack_id)
return stack.model_dump()
@@ -74,7 +74,7 @@ def configure_deck_tools(mcp: FastMCP):
await ctx.warning(
"This resource is deprecated, use the deck_get_cards tool instead"
)
client: NextcloudClient = ctx.request_context.lifespan_context.client
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]
@@ -87,7 +87,7 @@ def configure_deck_tools(mcp: FastMCP):
await ctx.warning(
"This resource is deprecated, use the deck_get_card tool instead"
)
client: NextcloudClient = ctx.request_context.lifespan_context.client
client = get_client(ctx)
card = await client.deck.get_card(board_id, stack_id, card_id)
return card.model_dump()
@@ -98,7 +98,7 @@ def configure_deck_tools(mcp: FastMCP):
await ctx.warning(
"This resource is deprecated, use the deck_get_labels tool instead"
)
client: NextcloudClient = ctx.request_context.lifespan_context.client
client = get_client(ctx)
board = await client.deck.get_board(board_id)
return [label.model_dump() for label in board.labels]
@@ -109,7 +109,7 @@ def configure_deck_tools(mcp: FastMCP):
await ctx.warning(
"This resource is deprecated, use the deck_get_label tool instead"
)
client: NextcloudClient = ctx.request_context.lifespan_context.client
client = get_client(ctx)
label = await client.deck.get_label(board_id, label_id)
return label.model_dump()
@@ -118,28 +118,28 @@ def configure_deck_tools(mcp: FastMCP):
@mcp.tool()
async def deck_get_boards(ctx: Context) -> list[DeckBoard]:
"""Get all Nextcloud Deck boards"""
client: NextcloudClient = ctx.request_context.lifespan_context.client
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: NextcloudClient = ctx.request_context.lifespan_context.client
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: NextcloudClient = ctx.request_context.lifespan_context.client
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: NextcloudClient = ctx.request_context.lifespan_context.client
client = get_client(ctx)
stack = await client.deck.get_stack(board_id, stack_id)
return stack
@@ -148,7 +148,7 @@ def configure_deck_tools(mcp: FastMCP):
ctx: Context, board_id: int, stack_id: int
) -> list[DeckCard]:
"""Get all cards in a Nextcloud Deck stack"""
client: NextcloudClient = ctx.request_context.lifespan_context.client
client = get_client(ctx)
stack = await client.deck.get_stack(board_id, stack_id)
if stack.cards:
return stack.cards
@@ -159,21 +159,21 @@ def configure_deck_tools(mcp: FastMCP):
ctx: Context, board_id: int, stack_id: int, card_id: int
) -> DeckCard:
"""Get details of a specific Nextcloud Deck card"""
client: NextcloudClient = ctx.request_context.lifespan_context.client
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: NextcloudClient = ctx.request_context.lifespan_context.client
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: NextcloudClient = ctx.request_context.lifespan_context.client
client = get_client(ctx)
label = await client.deck.get_label(board_id, label_id)
return label
@@ -189,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)
@@ -206,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)
@@ -226,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,
@@ -245,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,
@@ -277,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
)
@@ -318,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,
@@ -351,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,
@@ -372,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,
@@ -393,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,
@@ -421,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
)
@@ -445,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)
@@ -465,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,
@@ -484,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,
@@ -506,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,
@@ -528,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,
@@ -551,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,
@@ -573,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
+67 -20
View File
@@ -1,20 +1,20 @@
import logging
from httpx import HTTPStatusError
from httpx import HTTPStatusError, RequestError
from mcp.server.fastmcp import Context, FastMCP
from mcp.shared.exceptions import McpError
from mcp.types import ErrorData
from mcp.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,7 +27,7 @@ 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)
@@ -35,7 +35,7 @@ def configure_notes_tools(mcp: FastMCP):
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(
@@ -57,10 +57,17 @@ def configure_notes_tools(mcp: FastMCP):
"""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)
except RequestError as e:
raise McpError(
ErrorData(
code=-1,
message=f"Network error retrieving note {note_id}: {str(e)}",
)
)
except HTTPStatusError as e:
if e.response.status_code == 404:
raise McpError(ErrorData(code=-1, message=f"Note {note_id} not found"))
@@ -81,7 +88,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,
@@ -92,6 +99,10 @@ def configure_notes_tools(mcp: FastMCP):
return CreateNoteResponse(
id=note.id, title=note.title, category=note.category, etag=note.etag
)
except RequestError as e:
raise McpError(
ErrorData(code=-1, message=f"Network error creating note: {str(e)}")
)
except HTTPStatusError as e:
if e.response.status_code == 403:
raise McpError(
@@ -133,7 +144,7 @@ def configure_notes_tools(mcp: FastMCP):
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,
@@ -146,6 +157,12 @@ def configure_notes_tools(mcp: FastMCP):
return UpdateNoteResponse(
id=note.id, title=note.title, category=note.category, etag=note.etag
)
except RequestError as e:
raise McpError(
ErrorData(
code=-1, message=f"Network error updating note {note_id}: {str(e)}"
)
)
except HTTPStatusError as e:
if e.response.status_code == 404:
raise McpError(ErrorData(code=-1, message=f"Note {note_id} not found"))
@@ -183,7 +200,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
@@ -192,6 +209,13 @@ def configure_notes_tools(mcp: FastMCP):
return AppendContentResponse(
id=note.id, title=note.title, category=note.category, etag=note.etag
)
except RequestError as e:
raise McpError(
ErrorData(
code=-1,
message=f"Network error appending to note {note_id}: {str(e)}",
)
)
except HTTPStatusError as e:
if e.response.status_code == 404:
raise McpError(ErrorData(code=-1, message=f"Note {note_id} not found"))
@@ -220,7 +244,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)
@@ -238,6 +262,10 @@ def configure_notes_tools(mcp: FastMCP):
return SearchNotesResponse(
results=results, query=query, total_found=len(results)
)
except RequestError as e:
raise McpError(
ErrorData(code=-1, message=f"Network error searching notes: {str(e)}")
)
except HTTPStatusError as e:
if e.response.status_code == 403:
raise McpError(
@@ -261,10 +289,16 @@ 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: 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)
except RequestError as e:
raise McpError(
ErrorData(
code=-1, message=f"Network error getting note {note_id}: {str(e)}"
)
)
except HTTPStatusError as e:
if e.response.status_code == 404:
raise McpError(ErrorData(code=-1, message=f"Note {note_id} not found"))
@@ -285,7 +319,7 @@ def configure_notes_tools(mcp: FastMCP):
note_id: int, attachment_filename: str, ctx: Context
) -> dict[str, str]:
"""Get a specific attachment from a note"""
client: NextcloudClient = ctx.request_context.lifespan_context.client
client = get_client(ctx)
try:
content, mime_type = await client.webdav.get_note_attachment(
note_id=note_id, filename=attachment_filename
@@ -295,6 +329,13 @@ def configure_notes_tools(mcp: FastMCP):
"mimeType": mime_type,
"data": content,
}
except RequestError as e:
raise McpError(
ErrorData(
code=-1,
message=f"Network error getting attachment {attachment_filename} for note {note_id}: {str(e)}",
)
)
except HTTPStatusError as e:
if e.response.status_code == 404:
raise McpError(
@@ -322,7 +363,7 @@ def configure_notes_tools(mcp: FastMCP):
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(
@@ -330,6 +371,12 @@ def configure_notes_tools(mcp: FastMCP):
message=f"Note {note_id} deleted successfully",
deleted_id=note_id,
)
except RequestError as e:
raise McpError(
ErrorData(
code=-1, message=f"Network error deleting note {note_id}: {str(e)}"
)
)
except HTTPStatusError as e:
if e.response.status_code == 404:
raise McpError(ErrorData(code=-1, message=f"Note {note_id} not found"))
nextcloud_mcp_server/server/sharing.py
+134
View File
@@ -0,0 +1,134 @@
"""MCP tools for Nextcloud file/folder sharing operations."""
import json
from mcp.server.fastmcp import Context, FastMCP
from nextcloud_mcp_server.context import get_client
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
+7 -7
View File
@@ -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
+199 -61
View File
@@ -8,6 +8,8 @@ from nextcloud_mcp_server.utils.document_parser import (
parse_document,
)
from nextcloud_mcp_server.config import is_unstructured_parsing_enabled
from nextcloud_mcp_server.context import get_client
from nextcloud_mcp_server.models import FileInfo, SearchFilesResponse
logger = logging.getLogger(__name__)
@@ -23,15 +25,8 @@ def configure_webdav_tools(mcp: FastMCP):
Returns:
List of items with metadata including name, path, is_directory, size, content_type, last_modified
Examples:
# List root directory
await nc_webdav_list_directory("")
# 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()
@@ -61,7 +56,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)
# Check if this is a parseable document (PDF, DOCX, etc.)
@@ -122,15 +117,8 @@ def configure_webdav_tools(mcp: FastMCP):
Returns:
Dict with status_code indicating success
Examples:
# Write a text file
await nc_webdav_write_file("Documents/notes.md", "# My Notes\nContent here...")
# 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():
@@ -152,15 +140,8 @@ def configure_webdav_tools(mcp: FastMCP):
Returns:
Dict with status_code (201 for created, 405 if already exists)
Examples:
# Create a single directory
await nc_webdav_create_directory("NewProject")
# 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()
@@ -172,15 +153,8 @@ def configure_webdav_tools(mcp: FastMCP):
Returns:
Dict with status_code indicating result (404 if not found)
Examples:
# Delete a file
await nc_webdav_delete_resource("old_document.txt")
# 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()
@@ -196,21 +170,8 @@ def configure_webdav_tools(mcp: FastMCP):
Returns:
Dict with status_code indicating result (404 if source not found, 412 if destination exists and overwrite is False)
Examples:
# Rename a file
await nc_webdav_move_resource("document.txt", "new_name.txt")
# Move a file to another directory
await nc_webdav_move_resource("document.txt", "Archive/document.txt")
# Move a directory
await nc_webdav_move_resource("Projects/OldProject", "Projects/NewProject")
# 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
)
@@ -228,21 +189,198 @@ def configure_webdav_tools(mcp: FastMCP):
Returns:
Dict with status_code indicating result (404 if source not found, 412 if destination exists and overwrite is False)
Examples:
# Copy a file
await nc_webdav_copy_resource("document.txt", "document_copy.txt")
# Copy a file to another directory
await nc_webdav_copy_resource("document.txt", "Backup/document.txt")
# Copy a directory
await nc_webdav_copy_resource("Projects/ProjectA", "Projects/ProjectA_Backup")
# 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
)
@mcp.tool()
async def nc_webdav_search_files(
ctx: Context,
scope: str = "",
name_pattern: str | None = None,
mime_type: str | None = None,
only_favorites: bool = False,
limit: int | None = None,
) -> SearchFilesResponse:
"""Search for files in NextCloud using WebDAV SEARCH.
This is a high-level search tool that supports common search patterns.
For more complex queries, use the specific search tools.
Args:
scope: Directory path to search in (empty string for user root)
name_pattern: File name pattern (supports % wildcard, e.g., "%.txt" for all text files)
mime_type: MIME type to filter by (supports % wildcard, e.g., "image/%" for all images)
only_favorites: If True, only return favorited files
limit: Maximum number of results to return
Returns:
SearchFilesResponse with list of matching files
"""
client = get_client(ctx)
# Build where conditions based on filters
conditions = []
if name_pattern:
conditions.append(
f"""
<d:like>
<d:prop>
<d:displayname/>
</d:prop>
<d:literal>{name_pattern}</d:literal>
</d:like>
"""
)
if mime_type:
conditions.append(
f"""
<d:like>
<d:prop>
<d:getcontenttype/>
</d:prop>
<d:literal>{mime_type}</d:literal>
</d:like>
"""
)
if only_favorites:
conditions.append(
"""
<d:eq>
<d:prop>
<oc:favorite/>
</d:prop>
<d:literal>1</d:literal>
</d:eq>
"""
)
# Combine conditions with AND if multiple
if len(conditions) > 1:
where_conditions = f"""
<d:and>
{"".join(conditions)}
</d:and>
"""
elif len(conditions) == 1:
where_conditions = conditions[0]
else:
where_conditions = None
# Include extended properties
properties = [
"displayname",
"getcontentlength",
"getcontenttype",
"getlastmodified",
"resourcetype",
"getetag",
"fileid",
"favorite",
]
results = await client.webdav.search_files(
scope=scope,
where_conditions=where_conditions,
properties=properties,
limit=limit,
)
# Convert to FileInfo models
file_infos = [FileInfo(**result) for result in results]
# Build filters applied dict
filters = {}
if name_pattern:
filters["name_pattern"] = name_pattern
if mime_type:
filters["mime_type"] = mime_type
if only_favorites:
filters["only_favorites"] = True
return SearchFilesResponse(
results=file_infos,
total_found=len(file_infos),
scope=scope,
filters_applied=filters if filters else None,
)
@mcp.tool()
async def nc_webdav_find_by_name(
pattern: str, ctx: Context, scope: str = "", limit: int | None = None
) -> SearchFilesResponse:
"""Find files by name pattern in NextCloud.
Args:
pattern: Name pattern to search for (supports % wildcard)
scope: Directory path to search in (empty string for user root)
limit: Maximum number of results to return
Returns:
SearchFilesResponse with list of matching files
"""
client = get_client(ctx)
results = await client.webdav.find_by_name(
pattern=pattern, scope=scope, limit=limit
)
file_infos = [FileInfo(**result) for result in results]
return SearchFilesResponse(
results=file_infos,
total_found=len(file_infos),
scope=scope,
filters_applied={"name_pattern": pattern},
)
@mcp.tool()
async def nc_webdav_find_by_type(
mime_type: str, ctx: Context, scope: str = "", limit: int | None = None
) -> SearchFilesResponse:
"""Find files by MIME type in NextCloud.
Args:
mime_type: MIME type to search for (supports % wildcard)
scope: Directory path to search in (empty string for user root)
limit: Maximum number of results to return
Returns:
SearchFilesResponse with list of matching files
"""
client = get_client(ctx)
results = await client.webdav.find_by_type(
mime_type=mime_type, scope=scope, limit=limit
)
file_infos = [FileInfo(**result) for result in results]
return SearchFilesResponse(
results=file_infos,
total_found=len(file_infos),
scope=scope,
filters_applied={"mime_type": mime_type},
)
@mcp.tool()
async def nc_webdav_list_favorites(
ctx: Context, scope: str = "", limit: int | None = None
) -> SearchFilesResponse:
"""List all favorite files in NextCloud.
Args:
scope: Directory path to search in (empty string for all favorites)
limit: Maximum number of results to return
Returns:
SearchFilesResponse with list of favorite files
"""
client = get_client(ctx)
results = await client.webdav.list_favorites(scope=scope, limit=limit)
file_infos = [FileInfo(**result) for result in results]
return SearchFilesResponse(
results=file_infos,
total_found=len(file_infos),
scope=scope,
filters_applied={"only_favorites": True},
)
pyproject.toml
+59 -14
View File
@@ -1,32 +1,59 @@
[project]
name = "nextcloud-mcp-server"
version = "0.12.5"
description = ""
version = "0.17.1"
description = "Model Context Protocol (MCP) server for Nextcloud integration - enables AI assistants to interact with Nextcloud data"
authors = [
{name = "Chris Coutinho",email = "chris@coutinho.io"}
{name = "Chris Coutinho", email = "chris@coutinho.io"}
]
readme = "README.md"
license = {text = "AGPL-3.0-only"}
requires-python = ">=3.11"
keywords = ["nextcloud", "mcp", "model-context-protocol", "llm", "ai", "claude", "webdav", "caldav", "carddav"]
dependencies = [
"mcp[cli] (>=1.16,<1.17)",
"mcp[cli] (>=1.18,<1.19)",
"httpx (>=0.28.1,<0.29.0)",
"pillow (>=11.2.1,<12.0.0)",
"pillow (>=12.0.0,<12.1.0)",
"icalendar (>=6.0.0,<7.0.0)",
"pythonvcard4>=0.2.0",
"pydantic>=2.11.4",
"click>=8.1.8",
"caldav",
]
classifiers = [
"Development Status :: 4 - Beta",
"Intended Audience :: Developers",
"License :: OSI Approved :: GNU Affero General Public License v3",
"Programming Language :: Python :: 3",
"Programming Language :: Python :: 3.11",
"Programming Language :: Python :: 3.12",
"Topic :: Scientific/Engineering :: Artificial Intelligence",
"Topic :: Communications",
"Topic :: Internet :: WWW/HTTP",
]
[project.urls]
Homepage = "https://github.com/cbcoutinho/nextcloud-mcp-server"
Documentation = "https://github.com/cbcoutinho/nextcloud-mcp-server#readme"
Repository = "https://github.com/cbcoutinho/nextcloud-mcp-server"
"Bug Tracker" = "https://github.com/cbcoutinho/nextcloud-mcp-server/issues"
Changelog = "https://github.com/cbcoutinho/nextcloud-mcp-server/blob/master/CHANGELOG.md"
[tool.pytest.ini_options]
asyncio_mode = "auto"
asyncio_default_test_loop_scope = "session"
asyncio_default_fixture_loop_scope = "session"
anyio_mode = "auto"
addopts = "-p no:asyncio" # Disable pytest-asyncio plugin, use only anyio
log_cli = 1
log_cli_level = "INFO"
log_level = "INFO"
log_cli_level = "ERROR"
log_level = "ERROR"
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",
]
# Timeout settings to prevent tests from hanging indefinitely
timeout = 180 # 3 minutes default timeout per test (includes fixture setup)
timeout_func_only = false # Timeout includes fixture setup/teardown
[tool.commitizen]
name = "cz_conventional_commits"
@@ -36,20 +63,38 @@ version_provider = "uv"
update_changelog_on_bump = true
major_version_zero = true
[tool.ruff.lint]
extend-select = ["I"]
[tool.uv.sources]
caldav = { git = "https://github.com/cbcoutinho/caldav", branch = "feature/httpx" }
[build-system]
requires = ["poetry-core>=2.0.0,<3.0.0"]
build-backend = "poetry.core.masonry.api"
requires = ["uv_build>=0.9.4,<0.10.0"]
build-backend = "uv_build"
[tool.uv.build-backend]
module-name = "nextcloud_mcp_server"
module-root = ""
[dependency-groups]
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",
"pytest-timeout>=2.3.1",
"ruff>=0.11.13",
"reportlab>=4.0.0",
]
[project.scripts]
nextcloud-mcp-server = "nextcloud_mcp_server.app:run"
[[tool.uv.index]]
name = "testpypi"
url = "https://test.pypi.org/simple/"
publish-url = "https://test.pypi.org/legacy/"
explicit = true
tests/client/calendar/conftest.py
+11
View File
@@ -0,0 +1,11 @@
"""Shared fixtures for calendar integration tests.
Note: The temporary_calendar fixture is defined in tests/conftest.py and uses
a shared session-scoped calendar to avoid Nextcloud rate limiting issues.
This conftest.py exists for any calendar-specific fixtures that might be needed
in the future.
"""
import logging
logger = logging.getLogger(__name__)
tests/integration/test_calendar_operations.py → tests/client/calendar/test_calendar_operations.py
+20 -48
View File
@@ -1,4 +1,9 @@
"""Integration tests for Calendar CalDAV operations."""
"""Integration tests for Calendar CalDAV operations.
Note: These tests use the shared temporary_calendar fixture from conftest.py
which reuses a session-scoped calendar to avoid Nextcloud rate limiting issues.
Each test cleans up its own events/todos but shares the same calendar.
"""
import logging
import uuid
@@ -15,50 +20,13 @@ logger = logging.getLogger(__name__)
pytestmark = pytest.mark.integration
@pytest.fixture
def test_calendar_name():
"""Unique calendar name for testing."""
return f"test_calendar_{uuid.uuid4().hex[:8]}"
@pytest.fixture
async def temporary_calendar(nc_client: NextcloudClient, test_calendar_name: str):
"""Create a temporary calendar for testing and clean up afterward."""
calendar_name = test_calendar_name
try:
# Create a test calendar
logger.info(f"Creating temporary calendar: {calendar_name}")
result = await nc_client.calendar.create_calendar(
calendar_name=calendar_name,
display_name=f"Test Calendar {calendar_name}",
description="Temporary calendar for integration testing",
color="#FF5722",
)
if result["status_code"] not in [200, 201]:
pytest.skip(f"Failed to create temporary calendar: {result}")
logger.info(f"Created temporary calendar: {calendar_name}")
yield calendar_name
except Exception as e:
logger.error(f"Error setting up temporary calendar: {e}")
pytest.skip(f"Calendar setup failed: {e}")
finally:
# Cleanup: Delete the temporary calendar
try:
logger.info(f"Cleaning up temporary calendar: {calendar_name}")
await nc_client.calendar.delete_calendar(calendar_name)
logger.info(f"Successfully deleted temporary calendar: {calendar_name}")
except Exception as e:
logger.error(f"Error deleting temporary calendar {calendar_name}: {e}")
@pytest.fixture
async def temporary_event(nc_client: NextcloudClient, temporary_calendar: str):
"""Create a temporary event for testing and clean up afterward."""
"""Create a temporary event for testing and clean up afterward.
Uses the shared temporary_calendar fixture from conftest.py which reuses
a session-scoped calendar to avoid Nextcloud rate limiting.
"""
event_uid = None
calendar_name = temporary_calendar
@@ -351,11 +319,11 @@ async def test_get_nonexistent_event(
calendar_name = temporary_calendar
fake_uid = f"nonexistent-{uuid.uuid4()}"
with pytest.raises(HTTPStatusError) as exc_info:
# caldav library raises generic Exception for missing events, not HTTPStatusError
with pytest.raises(Exception, match="not found"):
await nc_client.calendar.get_event(calendar_name, fake_uid)
assert exc_info.value.response.status_code == 404
logger.info(f"Correctly got 404 for nonexistent event: {fake_uid}")
logger.info(f"Correctly raised exception for nonexistent event: {fake_uid}")
async def test_delete_nonexistent_event(
@@ -420,7 +388,11 @@ async def test_calendar_operations_error_handling(
# Test with non-existent calendar
fake_calendar = f"nonexistent_calendar_{uuid.uuid4().hex}"
with pytest.raises(HTTPStatusError):
await nc_client.calendar.get_calendar_events(fake_calendar)
# caldav library returns empty list for non-existent calendars, doesn't raise
# Testing that it doesn't crash and returns empty results
events = await nc_client.calendar.get_calendar_events(fake_calendar)
assert isinstance(events, list)
# Empty list is expected for non-existent calendar
assert len(events) == 0
logger.info("Error handling tests completed successfully")
tests/integration/test_field_preservation.py → tests/client/calendar/test_field_preservation.py
+49 -58
View File
@@ -5,16 +5,17 @@ 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__)
@pytest.mark.integration
async def test_calendar_event_custom_fields_preservation(nc_client):
"""Test that demonstrates loss of non-supported iCal fields during round-trip operations."""
"""Test that custom iCal fields are preserved during round-trip update operations."""
calendar_name = "personal"
# Create an event with standard fields
@@ -31,7 +32,12 @@ async def test_calendar_event_custom_fields_preservation(nc_client):
event_uid = result["uid"]
try:
# Now manually inject a custom iCal property by creating a new version with raw iCal
# Get the calendar object from the caldav library
calendar = nc_client.calendar._get_calendar(calendar_name)
event = await calendar.event_by_uid(event_uid)
await event.load()
# Now manually inject custom iCal properties into the raw data
# This simulates what would happen if the event was created by another CalDAV client
# with extended properties
custom_ical = f"""BEGIN:VCALENDAR
@@ -56,22 +62,15 @@ LAST-MODIFIED:{datetime.now().strftime("%Y%m%dT%H%M%SZ")}
END:VEVENT
END:VCALENDAR"""
# Direct CalDAV PUT to inject the custom iCal
event_path = f"/remote.php/dav/calendars/{nc_client.calendar.username}/{calendar_name}/{event_uid}.ics"
await nc_client.calendar._make_request(
"PUT",
event_path,
content=custom_ical,
headers={"Content-Type": "text/calendar; charset=utf-8"},
)
# Update the event's raw data and save
event.data = custom_ical
await event.save()
logger.info(f"Injected custom iCal properties into event {event_uid}")
# Retrieve the event to confirm custom fields are present in raw iCal
response = await nc_client.calendar._make_request(
"GET", event_path, headers={"Accept": "text/calendar"}
)
raw_ical_before = response.text
# Reload the event to confirm custom fields are present
await event.load()
raw_ical_before = event.data
logger.info("Raw iCal before update:")
logger.info(raw_ical_before)
@@ -92,31 +91,24 @@ END:VCALENDAR"""
await nc_client.calendar.update_event(calendar_name, event_uid, update_data)
logger.info(f"Updated event {event_uid} through MCP client")
# Retrieve the event again to see if custom fields survived
response_after = await nc_client.calendar._make_request(
"GET", event_path, headers={"Accept": "text/calendar"}
)
raw_ical_after = response_after.text
# Reload the event to see if custom fields survived
await event.load()
raw_ical_after = event.data
logger.info("Raw iCal after update:")
logger.info(raw_ical_after)
# THIS IS THE TEST THAT SHOULD FAIL - custom fields should be preserved but won't be
try:
assert (
"X-CUSTOM-FIELD:This is a custom field that should be preserved"
in raw_ical_after
), "Custom field X-CUSTOM-FIELD was lost during round-trip update"
assert "X-VENDOR-SPECIFIC:Vendor specific data" in raw_ical_after, (
"Custom field X-VENDOR-SPECIFIC was lost during round-trip update"
)
logger.info(
"✓ Custom fields were preserved (unexpected - this should fail with current implementation)"
)
except AssertionError as e:
logger.error(f"✗ Custom fields were lost during round-trip update: {e}")
# Re-raise to show the test failure
raise
# THIS IS THE CRITICAL TEST - custom fields should be preserved
assert (
"X-CUSTOM-FIELD:This is a custom field that should be preserved"
in raw_ical_after
), "Custom field X-CUSTOM-FIELD was lost during round-trip update"
assert "X-VENDOR-SPECIFIC:Vendor specific data" in raw_ical_after, (
"Custom field X-VENDOR-SPECIFIC was lost during round-trip update"
)
logger.info("✓ Custom fields were preserved during update")
finally:
# Cleanup
@@ -298,7 +290,7 @@ END:VCARD"""
@pytest.mark.integration
async def test_calendar_event_roundtrip_data_loss_demonstration(nc_client):
"""Demonstrates specific data loss scenarios in calendar events."""
"""Test that extended iCal properties are preserved during round-trip update operations."""
calendar_name = "personal"
event_data = {
@@ -312,6 +304,11 @@ async def test_calendar_event_roundtrip_data_loss_demonstration(nc_client):
event_uid = result["uid"]
try:
# Get the calendar object and event
calendar = nc_client.calendar._get_calendar(calendar_name)
event = await calendar.event_by_uid(event_uid)
await event.load()
# Inject additional iCal properties that are valid but not supported by our parser
extended_ical = f"""BEGIN:VCALENDAR
VERSION:2.0
@@ -341,20 +338,13 @@ LAST-MODIFIED:{datetime.now().strftime("%Y%m%dT%H%M%SZ")}
END:VEVENT
END:VCALENDAR"""
# Inject the extended iCal
event_path = f"/remote.php/dav/calendars/{nc_client.calendar.username}/{calendar_name}/{event_uid}.ics"
await nc_client.calendar._make_request(
"PUT",
event_path,
content=extended_ical,
headers={"Content-Type": "text/calendar; charset=utf-8"},
)
# Update the event's raw data and save
event.data = extended_ical
await event.save()
# Verify extended properties are present
response = await nc_client.calendar._make_request(
"GET", event_path, headers={"Accept": "text/calendar"}
)
original_ical = response.text
# Reload to verify extended properties are present
await event.load()
original_ical = event.data
# Confirm extended properties exist
extended_properties = [
@@ -391,11 +381,9 @@ END:VCALENDAR"""
update_data = {"location": "Conference Room B"} # Simple location change
await nc_client.calendar.update_event(calendar_name, event_uid, update_data)
# Check what survived the round-trip
response_after = await nc_client.calendar._make_request(
"GET", event_path, headers={"Accept": "text/calendar"}
)
updated_ical = response_after.text
# Reload the event to check what survived the round-trip
await event.load()
updated_ical = event.data
logger.info("Checking which properties survived the update...")
@@ -422,13 +410,16 @@ END:VCALENDAR"""
lost.append(prop)
logger.info(f"Properties that SURVIVED: {survived}")
logger.error(f"Properties that were LOST: {lost}")
if lost:
logger.error(f"Properties that were LOST: {lost}")
# This test should fail - we expect data loss
# Assert that all extended properties were preserved
assert len(lost) == 0, (
f"Round-trip update lost {len(lost)} extended properties: {lost}"
)
logger.info("✓ All extended properties preserved during update")
finally:
try:
await nc_client.calendar.delete_event(calendar_name, event_uid)
tests/client/calendar/test_task_operations.py
+498
View File
@@ -0,0 +1,498 @@
"""Integration tests for Calendar VTODO (task) operations."""
import logging
import uuid
from datetime import datetime, timedelta
import pytest
from httpx import HTTPStatusError
from nextcloud_mcp_server.client import NextcloudClient
logger = logging.getLogger(__name__)
# Mark all tests in this module as integration tests
pytestmark = pytest.mark.integration
@pytest.fixture
async def temporary_todo(nc_client: NextcloudClient, temporary_calendar: str):
"""Create a temporary todo for testing and clean up afterward."""
todo_uid = None
calendar_name = temporary_calendar
# Create a test todo
tomorrow = datetime.now() + timedelta(days=1)
todo_data = {
"summary": f"Test Task {uuid.uuid4().hex[:8]}",
"description": "Test todo created by integration tests",
"status": "NEEDS-ACTION",
"priority": 5,
"due": tomorrow.strftime("%Y-%m-%dT18:00:00"),
"categories": "testing",
}
try:
logger.info(f"Creating temporary todo in calendar: {calendar_name}")
result = await nc_client.calendar.create_todo(calendar_name, todo_data)
todo_uid = result.get("uid")
if not todo_uid:
pytest.fail("Failed to create temporary todo")
logger.info(f"Created temporary todo with UID: {todo_uid}")
yield {"uid": todo_uid, "calendar_name": calendar_name, "data": todo_data}
finally:
# Cleanup
if todo_uid:
try:
logger.info(f"Cleaning up temporary todo: {todo_uid}")
await nc_client.calendar.delete_todo(calendar_name, todo_uid)
logger.info(f"Successfully deleted temporary todo: {todo_uid}")
except HTTPStatusError as e:
if e.response.status_code != 404:
logger.error(f"Error deleting temporary todo {todo_uid}: {e}")
except Exception as e:
logger.error(
f"Unexpected error deleting temporary todo {todo_uid}: {e}"
)
# ============= Basic CRUD Tests =============
async def test_create_and_delete_todo(
nc_client: NextcloudClient, temporary_calendar: str
):
"""Test creating and deleting a basic todo."""
calendar_name = temporary_calendar
# Create todo
tomorrow = datetime.now() + timedelta(days=1)
todo_data = {
"summary": "Integration Test Task",
"description": "Test task for integration testing",
"status": "NEEDS-ACTION",
"priority": 3,
"due": tomorrow.strftime("%Y-%m-%dT18:00:00"),
"categories": "testing,integration",
}
try:
result = await nc_client.calendar.create_todo(calendar_name, todo_data)
assert "uid" in result
assert result["status_code"] in [200, 201, 204]
todo_uid = result["uid"]
logger.info(f"Created todo with UID: {todo_uid}")
# Verify todo was created by listing todos
todos = await nc_client.calendar.list_todos(calendar_name)
todo_uids = [todo.get("uid") for todo in todos]
assert todo_uid in todo_uids
# Find our todo in the list
our_todo = next((t for t in todos if t.get("uid") == todo_uid), None)
assert our_todo is not None
assert our_todo["summary"] == "Integration Test Task"
assert our_todo["status"] == "NEEDS-ACTION"
assert our_todo["priority"] == 3
# Delete todo
delete_result = await nc_client.calendar.delete_todo(calendar_name, todo_uid)
assert delete_result["status_code"] in [200, 204, 404]
logger.info(f"Successfully deleted todo: {todo_uid}")
except Exception as e:
logger.error(f"Test failed: {e}")
raise
async def test_list_todos(nc_client: NextcloudClient, temporary_calendar: str):
"""Test listing todos in a calendar."""
calendar_name = temporary_calendar
# Create multiple todos
todo_uids = []
for i in range(3):
todo_data = {
"summary": f"Test Task {i + 1}",
"description": f"Task number {i + 1}",
"status": "NEEDS-ACTION",
"priority": i + 1,
}
result = await nc_client.calendar.create_todo(calendar_name, todo_data)
todo_uids.append(result["uid"])
try:
# List todos
todos = await nc_client.calendar.list_todos(calendar_name)
assert isinstance(todos, list)
assert len(todos) >= 3 # At least our 3 todos
# Check structure
for todo in todos:
assert "uid" in todo
assert "summary" in todo
assert "status" in todo
assert "priority" in todo
# Verify our todos are in the list
listed_uids = [todo["uid"] for todo in todos]
for uid in todo_uids:
assert uid in listed_uids
logger.info(f"Found {len(todos)} todos in calendar")
finally:
# Cleanup
for uid in todo_uids:
try:
await nc_client.calendar.delete_todo(calendar_name, uid)
except Exception:
pass
async def test_update_todo(nc_client: NextcloudClient, temporary_todo: dict):
"""Test updating an existing todo."""
calendar_name = temporary_todo["calendar_name"]
todo_uid = temporary_todo["uid"]
# Update todo data
updated_data = {
"summary": "Updated Test Task Title",
"description": "Updated description for test task",
"status": "IN-PROCESS",
"priority": 1, # High priority
"percent_complete": 50,
}
try:
result = await nc_client.calendar.update_todo(
calendar_name, todo_uid, updated_data
)
assert result["uid"] == todo_uid
# Verify updates by listing todos
todos = await nc_client.calendar.list_todos(calendar_name)
updated_todo = next((t for t in todos if t["uid"] == todo_uid), None)
assert updated_todo is not None
assert updated_todo["summary"] == "Updated Test Task Title"
assert updated_todo["description"] == "Updated description for test task"
assert updated_todo["status"] == "IN-PROCESS"
assert updated_todo["priority"] == 1
assert updated_todo["percent_complete"] == 50
logger.info(f"Successfully updated todo: {todo_uid}")
except Exception as e:
logger.error(f"Todo update test failed: {e}")
raise
async def test_todo_with_dates(nc_client: NextcloudClient, temporary_calendar: str):
"""Test creating a todo with start, due, and completed dates."""
calendar_name = temporary_calendar
now = datetime.now()
start_date = now + timedelta(days=1)
due_date = now + timedelta(days=7)
todo_data = {
"summary": "Task with Dates",
"description": "Test task with various date fields",
"status": "NEEDS-ACTION",
"dtstart": start_date.strftime("%Y-%m-%dT09:00:00"),
"due": due_date.strftime("%Y-%m-%dT17:00:00"),
}
try:
result = await nc_client.calendar.create_todo(calendar_name, todo_data)
todo_uid = result["uid"]
logger.info(f"Created todo with dates, UID: {todo_uid}")
# Verify dates
todos = await nc_client.calendar.list_todos(calendar_name)
created_todo = next((t for t in todos if t["uid"] == todo_uid), None)
assert created_todo is not None
assert created_todo["summary"] == "Task with Dates"
assert "dtstart" in created_todo
assert "due" in created_todo
# Cleanup
await nc_client.calendar.delete_todo(calendar_name, todo_uid)
except Exception as e:
logger.error(f"Date handling test failed: {e}")
raise
# ============= Advanced Feature Tests =============
async def test_todo_status_transitions(
nc_client: NextcloudClient, temporary_calendar: str
):
"""Test transitioning through different todo statuses."""
calendar_name = temporary_calendar
todo_data = {
"summary": "Status Transition Test",
"description": "Testing status changes",
"status": "NEEDS-ACTION",
}
result = await nc_client.calendar.create_todo(calendar_name, todo_data)
todo_uid = result["uid"]
try:
# Transition: NEEDS-ACTION → IN-PROCESS
await nc_client.calendar.update_todo(
calendar_name,
todo_uid,
{"status": "IN-PROCESS", "percent_complete": 25},
)
todos = await nc_client.calendar.list_todos(calendar_name)
todo = next((t for t in todos if t["uid"] == todo_uid), None)
assert todo["status"] == "IN-PROCESS"
assert todo["percent_complete"] == 25
# Transition: IN-PROCESS → COMPLETED
completed_time = datetime.now().strftime("%Y-%m-%dT%H:%M:%S")
await nc_client.calendar.update_todo(
calendar_name,
todo_uid,
{
"status": "COMPLETED",
"percent_complete": 100,
"completed": completed_time,
},
)
todos = await nc_client.calendar.list_todos(calendar_name)
todo = next((t for t in todos if t["uid"] == todo_uid), None)
assert todo["status"] == "COMPLETED"
assert todo["percent_complete"] == 100
assert "completed" in todo
logger.info(f"Successfully transitioned todo through statuses: {todo_uid}")
finally:
await nc_client.calendar.delete_todo(calendar_name, todo_uid)
async def test_todo_priority_levels(
nc_client: NextcloudClient, temporary_calendar: str
):
"""Test different priority levels (0=undefined, 1=highest, 9=lowest)."""
calendar_name = temporary_calendar
priorities = [0, 1, 5, 9]
priority_labels = {0: "Undefined", 1: "Highest", 5: "Medium", 9: "Lowest"}
todo_uids = []
try:
# Create todos with different priorities
for priority in priorities:
todo_data = {
"summary": f"Priority {priority} Task ({priority_labels[priority]})",
"status": "NEEDS-ACTION",
"priority": priority,
}
result = await nc_client.calendar.create_todo(calendar_name, todo_data)
todo_uids.append((result["uid"], priority))
# Verify all priorities
todos = await nc_client.calendar.list_todos(calendar_name)
for uid, expected_priority in todo_uids:
todo = next((t for t in todos if t["uid"] == uid), None)
assert todo is not None
assert todo["priority"] == expected_priority
logger.info(f"Successfully tested priority levels: {priorities}")
finally:
# Cleanup
for uid, _ in todo_uids:
try:
await nc_client.calendar.delete_todo(calendar_name, uid)
except Exception:
pass
async def test_todo_with_categories(
nc_client: NextcloudClient, temporary_calendar: str
):
"""Test creating a todo with multiple categories."""
calendar_name = temporary_calendar
todo_data = {
"summary": "Task with Categories",
"description": "Testing category support",
"status": "NEEDS-ACTION",
"categories": "work,meeting,important,quarterly",
}
try:
result = await nc_client.calendar.create_todo(calendar_name, todo_data)
todo_uid = result["uid"]
logger.info(f"Created todo with categories, UID: {todo_uid}")
# Verify categories
todos = await nc_client.calendar.list_todos(calendar_name)
created_todo = next((t for t in todos if t["uid"] == todo_uid), None)
assert created_todo is not None
assert "categories" in created_todo
categories_str = created_todo["categories"]
assert "work" in categories_str
assert "meeting" in categories_str
assert "important" in categories_str
assert "quarterly" in categories_str
# Cleanup
await nc_client.calendar.delete_todo(calendar_name, todo_uid)
except Exception as e:
logger.error(f"Categories test failed: {e}")
raise
async def test_search_todos_across_calendars(
nc_client: NextcloudClient, temporary_calendar: str, shared_calendar_2: str
):
"""Test searching for todos across multiple calendars.
Uses two shared test calendars to avoid rate limiting.
"""
# Use existing shared calendars to avoid rate limits
cal1_name = temporary_calendar # First shared test calendar
cal2_name = shared_calendar_2 # Second shared test calendar
try:
# Create todos in both calendars
todo1_data = {"summary": "Task in Calendar 1", "status": "NEEDS-ACTION"}
todo2_data = {"summary": "Task in Calendar 2", "status": "IN-PROCESS"}
result1 = await nc_client.calendar.create_todo(cal1_name, todo1_data)
result2 = await nc_client.calendar.create_todo(cal2_name, todo2_data)
# Search across all calendars
all_todos = await nc_client.calendar.search_todos_across_calendars()
assert isinstance(all_todos, list)
# Find our todos
todo1 = next((t for t in all_todos if t["uid"] == result1["uid"]), None)
todo2 = next((t for t in all_todos if t["uid"] == result2["uid"]), None)
assert todo1 is not None
assert todo2 is not None
assert "calendar_name" in todo1
assert "calendar_name" in todo2
assert todo1["calendar_name"] == cal1_name
assert todo2["calendar_name"] == cal2_name
logger.info(f"Found {len(all_todos)} todos across all calendars")
finally:
# Cleanup: Delete only the todos we created (calendars are reused/built-in)
try:
await nc_client.calendar.delete_todo(cal1_name, result1["uid"])
except Exception:
pass
try:
await nc_client.calendar.delete_todo(cal2_name, result2["uid"])
except Exception:
pass
# ============= Edge Case Tests =============
async def test_get_nonexistent_todo(
nc_client: NextcloudClient, temporary_calendar: str
):
"""Test attempting to retrieve a non-existent todo."""
calendar_name = temporary_calendar
fake_uid = f"nonexistent-{uuid.uuid4()}"
# List todos to ensure it doesn't exist
todos = await nc_client.calendar.list_todos(calendar_name)
matching_todos = [t for t in todos if t.get("uid") == fake_uid]
assert len(matching_todos) == 0
logger.info(f"Verified nonexistent todo UID: {fake_uid}")
async def test_delete_nonexistent_todo(
nc_client: NextcloudClient, temporary_calendar: str
):
"""Test deleting a non-existent todo."""
calendar_name = temporary_calendar
fake_uid = f"nonexistent-{uuid.uuid4()}"
result = await nc_client.calendar.delete_todo(calendar_name, fake_uid)
assert result["status_code"] == 404
logger.info(f"Correctly got 404 for deleting nonexistent todo: {fake_uid}")
async def test_list_todos_with_filters(
nc_client: NextcloudClient, temporary_calendar: str
):
"""Test listing todos with various filters."""
calendar_name = temporary_calendar
# Create todos with different statuses and priorities
test_todos = [
{
"summary": "High Priority Task",
"status": "NEEDS-ACTION",
"priority": 1,
"categories": "urgent",
},
{
"summary": "In Progress Task",
"status": "IN-PROCESS",
"priority": 5,
"categories": "work",
},
{
"summary": "Low Priority Task",
"status": "NEEDS-ACTION",
"priority": 9,
"categories": "someday",
},
]
created_uids = []
try:
# Create test todos
for todo_data in test_todos:
result = await nc_client.calendar.create_todo(calendar_name, todo_data)
created_uids.append(result["uid"])
# Test basic list without filters
all_todos = await nc_client.calendar.list_todos(calendar_name)
assert len(all_todos) >= 3
# Verify all our todos are in the list
our_todo_uids = [t["uid"] for t in all_todos if t["uid"] in created_uids]
assert len(our_todo_uids) == 3
logger.info(f"Successfully created and listed {len(created_uids)} test todos")
finally:
# Cleanup
for uid in created_uids:
try:
await nc_client.calendar.delete_todo(calendar_name, uid)
except Exception:
pass
tests/integration/test_contacts_operations.py → tests/client/contacts/test_contacts_operations.py
View File
tests/client/cookbook/test_cookbook_api.py
+386
View File
@@ -0,0 +1,386 @@
import asyncio
import logging
import uuid
import pytest
from httpx import HTTPStatusError
from nextcloud_mcp_server.client import NextcloudClient
logger = logging.getLogger(__name__)
# Mark all tests in this module as integration tests
pytestmark = pytest.mark.integration
async def test_cookbook_version(nc_client: NextcloudClient):
"""Test getting Cookbook app version."""
logger.info("Getting Cookbook app version")
version_data = await nc_client.cookbook.get_version()
assert "cookbook_version" in version_data
assert "api_version" in version_data
logger.info(f"Cookbook version: {version_data}")
async def test_cookbook_config(nc_client: NextcloudClient):
"""Test getting Cookbook app configuration."""
logger.info("Getting Cookbook app configuration")
config_data = await nc_client.cookbook.get_config()
# Config may be empty initially, just verify we can get it
assert isinstance(config_data, dict)
logger.info(f"Cookbook config: {config_data}")
async def test_cookbook_list_recipes(nc_client: NextcloudClient):
"""Test listing all recipes."""
logger.info("Listing all recipes")
recipes = await nc_client.cookbook.list_recipes()
assert isinstance(recipes, list)
logger.info(f"Found {len(recipes)} recipes")
async def test_cookbook_create_and_read_recipe(nc_client: NextcloudClient):
"""Test creating a recipe and reading it back."""
# Create a test recipe
recipe_name = f"Test Recipe {uuid.uuid4().hex[:8]}"
recipe_data = {
"name": recipe_name,
"description": "A test recipe for integration testing",
"recipeIngredient": ["100g flour", "2 eggs", "200ml milk"],
"recipeInstructions": [
"Mix ingredients",
"Cook for 20 minutes",
"Serve hot",
],
"recipeCategory": "Test",
"keywords": "test,integration",
"recipeYield": 4,
"prepTime": "PT15M",
"cookTime": "PT20M",
"totalTime": "PT35M",
}
logger.info(f"Creating recipe: {recipe_name}")
recipe_id = await nc_client.cookbook.create_recipe(recipe_data)
logger.info(f"Created recipe with ID: {recipe_id}")
try:
# Read the recipe back
logger.info(f"Reading recipe ID: {recipe_id}")
retrieved_recipe = await nc_client.cookbook.get_recipe(recipe_id)
assert retrieved_recipe["name"] == recipe_name
assert (
retrieved_recipe["description"] == "A test recipe for integration testing"
)
assert len(retrieved_recipe["recipeIngredient"]) == 3
assert len(retrieved_recipe["recipeInstructions"]) == 3
assert retrieved_recipe["recipeCategory"] == "Test"
assert retrieved_recipe["recipeYield"] == 4
logger.info(f"Successfully verified recipe: {recipe_name}")
finally:
# Clean up
logger.info(f"Deleting recipe ID: {recipe_id}")
await nc_client.cookbook.delete_recipe(recipe_id)
logger.info(f"Successfully deleted recipe ID: {recipe_id}")
async def test_cookbook_update_recipe(nc_client: NextcloudClient):
"""Test updating a recipe."""
# Create a test recipe
recipe_name = f"Test Recipe {uuid.uuid4().hex[:8]}"
recipe_data = {
"name": recipe_name,
"description": "Original description",
"recipeIngredient": ["100g flour"],
"recipeInstructions": ["Mix ingredients"],
"recipeCategory": "Original",
}
logger.info(f"Creating recipe for update test: {recipe_name}")
recipe_id = await nc_client.cookbook.create_recipe(recipe_data)
try:
# Get the current recipe first
current_recipe = await nc_client.cookbook.get_recipe(recipe_id)
# Update the recipe with all required fields
updated_data = current_recipe.copy()
updated_data["description"] = "Updated description"
updated_data["recipeIngredient"] = ["100g flour", "2 eggs"]
updated_data["recipeInstructions"] = ["Mix ingredients", "Cook"]
updated_data["recipeCategory"] = "Updated"
logger.info(f"Updating recipe ID: {recipe_id}")
updated_id = await nc_client.cookbook.update_recipe(recipe_id, updated_data)
assert updated_id == recipe_id
# Verify the update
await asyncio.sleep(1) # Allow propagation
updated_recipe = await nc_client.cookbook.get_recipe(recipe_id)
assert updated_recipe["description"] == "Updated description"
assert len(updated_recipe["recipeIngredient"]) == 2
assert len(updated_recipe["recipeInstructions"]) == 2
assert updated_recipe["recipeCategory"] == "Updated"
logger.info(f"Successfully updated recipe ID: {recipe_id}")
finally:
# Clean up
logger.info(f"Deleting recipe ID: {recipe_id}")
await nc_client.cookbook.delete_recipe(recipe_id)
async def test_cookbook_delete_nonexistent_recipe(nc_client: NextcloudClient):
"""Test deleting a non-existent recipe.
Note: The Cookbook API may return 502 or succeed silently for non-existent IDs
rather than 404. This test verifies the behavior."""
non_existent_id = 999999999
logger.info(f"Attempting to delete non-existent recipe ID: {non_existent_id}")
try:
result = await nc_client.cookbook.delete_recipe(non_existent_id)
logger.info(f"Delete returned: {result}")
# API may succeed silently or return an error message
assert isinstance(result, str)
except HTTPStatusError as e:
# API may return 404 or 502 for non-existent recipes
assert e.response.status_code in [404, 502]
logger.info(f"Delete correctly failed with {e.response.status_code}")
async def test_cookbook_import_recipe_from_url(nc_client: NextcloudClient):
"""Test importing a recipe from a URL.
This is the key feature test - importing recipes from URLs using schema.org metadata.
Uses an nginx container to serve reliable, controlled test data.
"""
# Use the nginx container hostname within the Docker network
test_url = "http://recipes/black-pepper-tofu"
logger.info(f"Importing recipe from nginx container: {test_url}")
try:
imported_recipe = await nc_client.cookbook.import_recipe(test_url)
logger.info(f"Successfully imported recipe: {imported_recipe.get('name')}")
# Verify basic recipe structure
assert "name" in imported_recipe
assert imported_recipe["name"] == "Black Pepper Tofu"
assert "id" in imported_recipe
# Verify schema.org fields were imported correctly
assert imported_recipe.get("description")
assert len(imported_recipe.get("recipeIngredient", [])) > 0
assert len(imported_recipe.get("recipeInstructions", [])) > 0
assert imported_recipe.get("recipeCategory") == "Main Course"
assert "tofu" in imported_recipe.get("keywords", "").lower()
recipe_id = int(imported_recipe["id"])
# Verify we can read it back
retrieved = await nc_client.cookbook.get_recipe(recipe_id)
assert retrieved["name"] == imported_recipe["name"]
logger.info(f"Verified imported recipe ID: {recipe_id}")
# Clean up
logger.info(f"Deleting imported recipe ID: {recipe_id}")
await nc_client.cookbook.delete_recipe(recipe_id)
logger.info("Successfully deleted imported recipe")
except HTTPStatusError as e:
if e.response.status_code == 409:
# Recipe already exists - this is acceptable in tests
logger.warning("Recipe already exists (409 conflict)")
pytest.skip("Recipe already exists in test environment")
elif e.response.status_code == 400:
# URL couldn't be imported
logger.error(
f"Failed to import recipe from nginx container: {test_url}. "
f"Status: {e.response.status_code}, Response: {e.response.text}"
)
raise
else:
raise
async def test_cookbook_search_recipes(nc_client: NextcloudClient):
"""Test searching for recipes."""
# Create a test recipe with unique keywords
unique_keyword = f"testkeyword{uuid.uuid4().hex[:8]}"
recipe_name = f"Test Recipe {uuid.uuid4().hex[:8]}"
recipe_data = {
"name": recipe_name,
"description": f"Recipe for testing search with {unique_keyword}",
"keywords": unique_keyword,
"recipeIngredient": ["test ingredient"],
"recipeInstructions": ["test instruction"],
}
logger.info(f"Creating recipe for search test with keyword: {unique_keyword}")
recipe_id = await nc_client.cookbook.create_recipe(recipe_data)
try:
# Allow time for indexing
await asyncio.sleep(2)
# Search for the recipe
logger.info(f"Searching for recipes with keyword: {unique_keyword}")
search_results = await nc_client.cookbook.search_recipes(unique_keyword)
assert isinstance(search_results, list)
# Should find at least our recipe
assert len(search_results) > 0
# Verify our recipe is in the results
found = any(str(r.get("id")) == str(recipe_id) for r in search_results)
assert found, f"Recipe {recipe_id} not found in search results"
logger.info(f"Successfully found recipe {recipe_id} in search results")
finally:
# Clean up
logger.info(f"Deleting recipe ID: {recipe_id}")
await nc_client.cookbook.delete_recipe(recipe_id)
async def test_cookbook_list_categories(nc_client: NextcloudClient):
"""Test listing recipe categories."""
logger.info("Listing recipe categories")
categories = await nc_client.cookbook.list_categories()
assert isinstance(categories, list)
logger.info(f"Found {len(categories)} categories")
# Each category should have name and recipe_count
if categories:
assert "name" in categories[0]
assert "recipe_count" in categories[0]
async def test_cookbook_get_recipes_in_category(nc_client: NextcloudClient):
"""Test getting recipes in a specific category."""
# Create a recipe in a test category
unique_category = f"TestCategory{uuid.uuid4().hex[:8]}"
recipe_name = f"Test Recipe {uuid.uuid4().hex[:8]}"
recipe_data = {
"name": recipe_name,
"recipeCategory": unique_category,
"recipeIngredient": ["test"],
"recipeInstructions": ["test"],
}
logger.info(f"Creating recipe in category: {unique_category}")
recipe_id = await nc_client.cookbook.create_recipe(recipe_data)
try:
# Allow time for indexing
await asyncio.sleep(2)
# Get recipes in this category
logger.info(f"Getting recipes in category: {unique_category}")
recipes_in_category = await nc_client.cookbook.get_recipes_in_category(
unique_category
)
assert isinstance(recipes_in_category, list)
assert len(recipes_in_category) > 0
# Verify our recipe is in the results
found = any(str(r.get("id")) == str(recipe_id) for r in recipes_in_category)
assert found, f"Recipe {recipe_id} not found in category {unique_category}"
logger.info(f"Successfully found recipe in category {unique_category}")
finally:
# Clean up
logger.info(f"Deleting recipe ID: {recipe_id}")
await nc_client.cookbook.delete_recipe(recipe_id)
async def test_cookbook_list_keywords(nc_client: NextcloudClient):
"""Test listing recipe keywords."""
logger.info("Listing recipe keywords")
keywords = await nc_client.cookbook.list_keywords()
assert isinstance(keywords, list)
logger.info(f"Found {len(keywords)} keywords")
# Each keyword should have name and recipe_count
if keywords:
assert "name" in keywords[0]
assert "recipe_count" in keywords[0]
async def test_cookbook_get_recipes_with_keywords(nc_client: NextcloudClient):
"""Test getting recipes with specific keywords.
Note: The keywords filtering may require exact keyword matches and sufficient
indexing time. This test uses a longer wait time."""
# Create a recipe with unique keywords
unique_keyword = f"testtag{uuid.uuid4().hex[:8]}"
recipe_name = f"Test Recipe {uuid.uuid4().hex[:8]}"
recipe_data = {
"name": recipe_name,
"keywords": f"{unique_keyword},integration",
"recipeIngredient": ["test"],
"recipeInstructions": ["test"],
}
logger.info(f"Creating recipe with keyword: {unique_keyword}")
recipe_id = await nc_client.cookbook.create_recipe(recipe_data)
try:
# Allow extra time for indexing
await asyncio.sleep(3)
# Trigger a reindex to ensure the recipe is indexed
await nc_client.cookbook.reindex()
await asyncio.sleep(2)
# Get recipes with this keyword
logger.info(f"Getting recipes with keyword: {unique_keyword}")
recipes_with_keywords = await nc_client.cookbook.get_recipes_with_keywords(
[unique_keyword]
)
assert isinstance(recipes_with_keywords, list)
# Keyword filtering might not find recipes immediately due to indexing
# Log the results for debugging
logger.info(
f"Found {len(recipes_with_keywords)} recipes with keyword {unique_keyword}"
)
if len(recipes_with_keywords) > 0:
# Verify our recipe is in the results if any are found
found = any(
str(r.get("id")) == str(recipe_id) for r in recipes_with_keywords
)
if found:
logger.info(f"Successfully found recipe with keyword {unique_keyword}")
else:
logger.warning(
f"Recipe {recipe_id} not in keyword results, but other recipes found"
)
else:
logger.warning(
f"No recipes found with keyword {unique_keyword} - may be indexing delay"
)
finally:
# Clean up
logger.info(f"Deleting recipe ID: {recipe_id}")
await nc_client.cookbook.delete_recipe(recipe_id)
async def test_cookbook_reindex(nc_client: NextcloudClient):
"""Test triggering a reindex of recipes."""
logger.info("Triggering recipe reindex")
result = await nc_client.cookbook.reindex()
# Should return a success message
assert isinstance(result, str)
logger.info(f"Reindex result: {result}")
tests/integration/test_deck_api.py → tests/client/deck/test_deck_api.py
+1 -1
View File
@@ -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/integration/test_attachments.py → tests/client/notes/test_attachments.py
View File
tests/integration/test_embedded_images.py → tests/client/notes/test_embedded_images.py
View File
tests/integration/test_notes_api.py → tests/client/notes/test_notes_api.py
View File
tests/integration/test_tables_api.py → tests/client/tables/test_tables_api.py
View File
tests/client/test_oauth.py
+103
View File
@@ -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 = [note async for note in 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:
_ = [note async for note in 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_playwright.py
+32
View File
@@ -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):
"""Test that OAuth client created via Playwright flow can access Nextcloud APIs."""
# Test 1: Check capabilities
capabilities = await nc_oauth_client.capabilities()
assert capabilities is not None
logger.info("OAuth client (Playwright) successfully fetched capabilities")
# Test 2: List notes
notes = [note async for note in nc_oauth_client.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
+172
View File
@@ -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.anyio
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.anyio
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.anyio
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/integration/test_webdav_cleanup.py → tests/client/webdav/test_webdav_cleanup.py
View File
tests/integration/test_webdav_operations.py → tests/client/webdav/test_webdav_operations.py
View File
tests/client/webdav/test_webdav_search.py
+268
View File
@@ -0,0 +1,268 @@
"""Integration tests for WebDAV search operations."""
import logging
import uuid
import pytest
from nextcloud_mcp_server.client import NextcloudClient
logger = logging.getLogger(__name__)
# Mark all tests in this module as integration tests
pytestmark = pytest.mark.integration
@pytest.fixture
async def test_search_setup(nc_client: NextcloudClient):
"""Create test files and directories for search testing."""
test_dir = f"mcp_search_test_{uuid.uuid4().hex[:8]}"
# Create base directory
await nc_client.webdav.create_directory(test_dir)
# Create various test files
test_files = [
# Text files
(f"{test_dir}/document1.txt", b"Sample document content", "text/plain"),
(f"{test_dir}/document2.txt", b"Another document", "text/plain"),
(f"{test_dir}/report.txt", b"Report content", "text/plain"),
# Markdown files
(f"{test_dir}/readme.md", b"# README\nMarkdown content", "text/markdown"),
(f"{test_dir}/notes.md", b"# Notes\nSome notes here", "text/markdown"),
# PDF (simulated as binary)
(
f"{test_dir}/presentation.pdf",
b"%PDF-1.4 fake pdf content",
"application/pdf",
),
# Subdirectory with files
(f"{test_dir}/subdir/nested.txt", b"Nested file content", "text/plain"),
]
# Create subdirectory
await nc_client.webdav.create_directory(f"{test_dir}/subdir")
# Write all test files
for file_path, content, content_type in test_files:
await nc_client.webdav.write_file(file_path, content, content_type)
logger.info(f"Created test directory with {len(test_files)} files: {test_dir}")
yield test_dir
# Cleanup
try:
await nc_client.webdav.delete_resource(test_dir)
logger.info(f"Cleaned up test directory: {test_dir}")
except Exception as e:
logger.warning(f"Failed to cleanup test directory {test_dir}: {e}")
async def test_find_by_name_exact(nc_client: NextcloudClient, test_search_setup: str):
"""Test finding files by exact name."""
results = await nc_client.webdav.find_by_name("readme.md", scope=test_search_setup)
assert len(results) >= 1, "Should find at least one readme.md file"
# Check that we found the right file
readme_files = [r for r in results if r.get("name") == "readme.md"]
assert len(readme_files) >= 1, "Should find readme.md"
logger.info(f"Found {len(results)} files matching 'readme.md'")
async def test_find_by_name_wildcard_extension(
nc_client: NextcloudClient, test_search_setup: str
):
"""Test finding files by extension using wildcard."""
# Find all .txt files
results = await nc_client.webdav.find_by_name("%.txt", scope=test_search_setup)
assert len(results) >= 3, "Should find at least 3 .txt files"
# Verify all results are .txt files
for result in results:
name = result.get("name", "")
assert name.endswith(".txt"), f"Expected .txt file, got {name}"
logger.info(f"Found {len(results)} .txt files")
async def test_find_by_name_wildcard_prefix(
nc_client: NextcloudClient, test_search_setup: str
):
"""Test finding files by name prefix using wildcard."""
# Find all files starting with "document"
results = await nc_client.webdav.find_by_name("document%", scope=test_search_setup)
assert len(results) >= 2, "Should find at least 2 files starting with 'document'"
# Verify all results start with "document"
for result in results:
name = result.get("name", "")
assert name.startswith("document"), (
f"Expected name to start with 'document', got {name}"
)
logger.info(f"Found {len(results)} files starting with 'document'")
async def test_find_by_type_text(nc_client: NextcloudClient, test_search_setup: str):
"""Test finding files by MIME type (text files)."""
# Find all text files
results = await nc_client.webdav.find_by_type("text/%", scope=test_search_setup)
assert len(results) >= 5, "Should find at least 5 text files"
# Verify all results are text files
for result in results:
content_type = result.get("content_type", "")
assert content_type.startswith("text/"), (
f"Expected text/* type, got {content_type}"
)
logger.info(f"Found {len(results)} text files")
async def test_find_by_type_specific(
nc_client: NextcloudClient, test_search_setup: str
):
"""Test finding files by specific MIME type."""
# Find PDF files
results = await nc_client.webdav.find_by_type(
"application/pdf", scope=test_search_setup
)
assert len(results) >= 1, "Should find at least 1 PDF file"
# Verify result is PDF
for result in results:
content_type = result.get("content_type", "")
assert content_type == "application/pdf", (
f"Expected application/pdf, got {content_type}"
)
logger.info(f"Found {len(results)} PDF files")
async def test_search_with_limit(nc_client: NextcloudClient, test_search_setup: str):
"""Test search with result limit."""
# Search for .txt files with limit of 2
results = await nc_client.webdav.find_by_name(
"%.txt", scope=test_search_setup, limit=2
)
# Should return at most 2 results
assert len(results) <= 2, f"Should return at most 2 results, got {len(results)}"
assert len(results) > 0, "Should return at least 1 result"
logger.info(f"Found {len(results)} files with limit=2")
async def test_search_files_combined_filters(
nc_client: NextcloudClient, test_search_setup: str
):
"""Test search with multiple filters combined."""
# This test uses the search_files method directly to test combined conditions
# Search for .txt files that match a specific pattern
where_conditions = """
<d:and>
<d:like>
<d:prop>
<d:displayname/>
</d:prop>
<d:literal>%.txt</d:literal>
</d:like>
<d:like>
<d:prop>
<d:displayname/>
</d:prop>
<d:literal>document%</d:literal>
</d:like>
</d:and>
"""
results = await nc_client.webdav.search_files(
scope=test_search_setup, where_conditions=where_conditions
)
# Should find document1.txt and document2.txt
assert len(results) >= 2, "Should find at least 2 files matching both conditions"
# Verify results match both conditions
for result in results:
name = result.get("name", "")
assert name.endswith(".txt"), f"Expected .txt file, got {name}"
assert name.startswith("document"), (
f"Expected name to start with 'document', got {name}"
)
logger.info(f"Found {len(results)} files matching combined filters")
async def test_search_empty_scope(nc_client: NextcloudClient, test_search_setup: str):
"""Test search in empty scope (user root)."""
# Search entire user root for a unique filename
unique_name = "readme.md"
results = await nc_client.webdav.find_by_name(unique_name, scope="")
# Should find at least the one we created
assert len(results) >= 1, f"Should find at least 1 file named {unique_name}"
logger.info(f"Found {len(results)} files in root scope")
async def test_search_subdirectory(nc_client: NextcloudClient, test_search_setup: str):
"""Test search within a subdirectory."""
# Search in the subdir for the nested file
results = await nc_client.webdav.find_by_name(
"nested.txt", scope=f"{test_search_setup}/subdir"
)
assert len(results) >= 1, "Should find nested.txt in subdirectory"
# Verify the file path
nested_file = results[0]
assert "nested.txt" in nested_file.get("name", ""), "Should find nested.txt"
logger.info(f"Found file in subdirectory: {nested_file.get('name')}")
async def test_search_no_results(nc_client: NextcloudClient, test_search_setup: str):
"""Test search that returns no results."""
# Search for a non-existent pattern
results = await nc_client.webdav.find_by_name(
"nonexistent_file_xyz123.txt", scope=test_search_setup
)
assert len(results) == 0, "Should return empty results for non-existent file"
logger.info("Search correctly returned no results for non-existent file")
async def test_search_properties_returned(
nc_client: NextcloudClient, test_search_setup: str
):
"""Test that search returns expected properties."""
results = await nc_client.webdav.find_by_name("readme.md", scope=test_search_setup)
assert len(results) >= 1, "Should find at least one file"
result = results[0]
# Check for expected properties
assert "name" in result, "Should include name property"
assert "path" in result, "Should include path property"
assert "is_directory" in result, "Should include is_directory property"
assert result["is_directory"] is False, "readme.md should not be a directory"
# Optional properties that may be present
optional_props = ["size", "content_type", "last_modified", "etag"]
logger.info(f"Result properties: {list(result.keys())}")
# At least some optional properties should be present
present_optional = [prop for prop in optional_props if prop in result]
assert len(present_optional) > 0, f"Should have at least one of {optional_props}"
logger.info(f"Search returned properties: {list(result.keys())}")
tests/conftest.py
+1129 -35
View File
File diff suppressed because it is too large Load Diff
tests/fixtures/nginx.conf
Vendored
+24
View File
@@ -0,0 +1,24 @@
events {
worker_connections 1024;
}
http {
include /etc/nginx/mime.types;
default_type text/html;
server {
listen 80;
server_name _;
location / {
root /usr/share/nginx/html;
try_files $uri $uri.html =404;
}
# Serve test_recipe.html at /black-pepper-tofu
location = /black-pepper-tofu {
root /usr/share/nginx/html;
try_files /test_recipe.html =404;
}
}
}
tests/fixtures/test_recipe.html
Vendored
+133
View File
@@ -0,0 +1,133 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>Black Pepper Tofu Recipe - Test Recipe</title>
<script type="application/ld+json">
{
"@context": "https://schema.org",
"@type": "Recipe",
"name": "Black Pepper Tofu",
"author": {
"@type": "Person",
"name": "Yotam Ottolenghi"
},
"datePublished": "2024-01-15",
"description": "A flavorful black pepper tofu dish with aromatic spices and crispy texture. Inspired by Yotam Ottolenghi's signature style.",
"prepTime": "PT15M",
"cookTime": "PT20M",
"totalTime": "PT35M",
"recipeYield": "4",
"recipeCategory": "Main Course",
"recipeCuisine": "Asian Fusion",
"keywords": "tofu, black pepper, vegetarian, vegan, ottolenghi",
"image": "https://example.com/black-pepper-tofu.jpg",
"recipeIngredient": [
"400g firm tofu, pressed and cubed",
"2 tablespoons black peppercorns, coarsely ground",
"3 tablespoons soy sauce",
"2 tablespoons rice vinegar",
"1 tablespoon maple syrup",
"2 tablespoons cornstarch",
"3 tablespoons vegetable oil",
"4 cloves garlic, minced",
"1 tablespoon fresh ginger, grated",
"2 spring onions, sliced",
"1 red bell pepper, sliced",
"Sesame seeds for garnish"
],
"recipeInstructions": [
{
"@type": "HowToStep",
"text": "Press the tofu for at least 15 minutes to remove excess moisture. Cut into 2cm cubes."
},
{
"@type": "HowToStep",
"text": "Toss tofu cubes with cornstarch until evenly coated."
},
{
"@type": "HowToStep",
"text": "Heat 2 tablespoons of oil in a large pan over medium-high heat. Add tofu and cook until golden and crispy on all sides, about 8-10 minutes. Remove and set aside."
},
{
"@type": "HowToStep",
"text": "In the same pan, add remaining oil. Add garlic, ginger, and ground black pepper. Cook for 1 minute until fragrant."
},
{
"@type": "HowToStep",
"text": "Add bell pepper and cook for 2-3 minutes until slightly softened."
},
{
"@type": "HowToStep",
"text": "Mix soy sauce, rice vinegar, and maple syrup. Pour into the pan and bring to a simmer."
},
{
"@type": "HowToStep",
"text": "Return the crispy tofu to the pan and toss to coat in the sauce. Cook for 2 minutes."
},
{
"@type": "HowToStep",
"text": "Garnish with spring onions and sesame seeds. Serve immediately with rice or noodles."
}
],
"nutrition": {
"@type": "NutritionInformation",
"calories": "280 kcal",
"proteinContent": "18 g",
"fatContent": "16 g",
"carbohydrateContent": "18 g",
"fiberContent": "3 g",
"servingSize": "1 serving"
}
}
</script>
</head>
<body>
<article>
<h1>Black Pepper Tofu</h1>
<p class="author">By Yotam Ottolenghi</p>
<p class="description">
A flavorful black pepper tofu dish with aromatic spices and crispy texture.
Inspired by Yotam Ottolenghi's signature style.
</p>
<div class="recipe-meta">
<p><strong>Prep Time:</strong> 15 minutes</p>
<p><strong>Cook Time:</strong> 20 minutes</p>
<p><strong>Total Time:</strong> 35 minutes</p>
<p><strong>Servings:</strong> 4</p>
</div>
<h2>Ingredients</h2>
<ul>
<li>400g firm tofu, pressed and cubed</li>
<li>2 tablespoons black peppercorns, coarsely ground</li>
<li>3 tablespoons soy sauce</li>
<li>2 tablespoons rice vinegar</li>
<li>1 tablespoon maple syrup</li>
<li>2 tablespoons cornstarch</li>
<li>3 tablespoons vegetable oil</li>
<li>4 cloves garlic, minced</li>
<li>1 tablespoon fresh ginger, grated</li>
<li>2 spring onions, sliced</li>
<li>1 red bell pepper, sliced</li>
<li>Sesame seeds for garnish</li>
</ul>
<h2>Instructions</h2>
<ol>
<li>Press the tofu for at least 15 minutes to remove excess moisture. Cut into 2cm cubes.</li>
<li>Toss tofu cubes with cornstarch until evenly coated.</li>
<li>Heat 2 tablespoons of oil in a large pan over medium-high heat. Add tofu and cook until golden and crispy on all sides, about 8-10 minutes. Remove and set aside.</li>
<li>In the same pan, add remaining oil. Add garlic, ginger, and ground black pepper. Cook for 1 minute until fragrant.</li>
<li>Add bell pepper and cook for 2-3 minutes until slightly softened.</li>
<li>Mix soy sauce, rice vinegar, and maple syrup. Pour into the pan and bring to a simmer.</li>
<li>Return the crispy tofu to the pan and toss to coat in the sauce. Cook for 2 minutes.</li>
<li>Garnish with spring onions and sesame seeds. Serve immediately with rice or noodles.</li>
</ol>
<h2>Nutrition Information</h2>
<p>Per serving: 280 calories, 18g protein, 16g fat, 18g carbohydrates, 3g fiber</p>
</article>
</body>
</html>
tests/load/README_OAUTH.md
+534
View File
@@ -0,0 +1,534 @@
# OAuth Multi-User Load Testing Framework
Comprehensive multi-user benchmarking system for testing OAuth-authenticated Nextcloud MCP server with realistic collaborative workflows.
## Quick Start
```bash
# 1. Ensure docker-compose is running
docker-compose up -d
# 2. Run a benchmark with 2 users for 30 seconds
uv run python -m tests.load.oauth_benchmark --users 2 --duration 30
# 3. Clean up test users (IMPORTANT - always run after benchmark)
uv run python -m tests.load.cleanup_loadtest_users
# Optional: Verify cleanup
uv run python -m tests.load.cleanup_loadtest_users --dry-run
```
## Overview
This framework extends the basic load testing infrastructure to support:
- **Multiple OAuth-authenticated users** running concurrently
- **Coordinated workflows** spanning multiple users (sharing, collaboration, permissions)
- **Per-user metrics** tracking individual user performance
- **Workflow-specific metrics** measuring cross-user operation latencies
- **Realistic scenarios** mimicking actual user collaboration patterns
- **Concurrent user creation** - all users created and authenticated in parallel for fast setup
## Architecture
### Components
```
tests/load/
├── oauth_pool.py # OAuth user pool management
├── oauth_workloads.py # Multi-user workflow definitions
├── oauth_metrics.py # Enhanced metrics collection
├── oauth_benchmark.py # Main CLI entry point
└── README_OAUTH.md # This file
```
### Key Classes
**OAuthUserPool** (`oauth_pool.py`)
- Manages N OAuth-authenticated users
- Handles token acquisition and storage
- Creates and manages MCP sessions per user
- Tracks per-user operation statistics
**UserSessionWrapper** (`oauth_pool.py`)
- Wraps MCP ClientSession for a specific user
- Automatic operation tracking
- Convenient tool/resource access methods
**Workflow** (`oauth_workloads.py`)
- Base class for multi-user coordinated workflows
- Step-by-step execution with timing
- Comprehensive error handling and reporting
**OAuthBenchmarkMetrics** (`oauth_metrics.py`)
- Per-user operation counts and latencies
- Workflow completion rates and timings
- Baseline operation statistics
- Detailed reporting and JSON export
## Available Workflows
### 1. NoteShareWorkflow
**Scenario**: Alice creates a note and shares it with Bob, who then reads it.
**Steps**:
1. User A creates a note
2. User A shares note with User B (read-only permissions)
3. User B lists their shared notes (measures propagation delay)
4. User B reads the shared note
**Metrics**: Creation latency, share propagation time, read latency
### 2. CollaborativeEditWorkflow
**Scenario**: Multiple users concurrently edit the same note.
**Steps**:
1. Owner creates a note
2. All users read the note simultaneously
3. All users append content concurrently
4. Owner verifies final state
**Metrics**: Concurrent read latency, concurrent write conflicts, final state consistency
### 3. FileShareAndDownloadWorkflow
**Scenario**: Alice uploads a file, shares it with Bob, who then downloads it.
**Steps**:
1. User A creates a file via WebDAV
2. User A shares file with User B (read-only)
3. User B lists their shares
4. User B downloads the file
**Metrics**: Upload latency, share creation, download latency
### 4. MixedOAuthWorkload
**Distribution**:
- 50% Baseline operations (individual user CRUD)
- 30% Note sharing workflows
- 15% Collaborative editing workflows
- 5% File sharing workflows
## Usage
### Basic Usage
```bash
# 4 users, 60-second test with mixed workload
uv run python -m tests.load.oauth_benchmark --users 4 --duration 60
# 10 users, 5-minute test
uv run python -m tests.load.oauth_benchmark -u 10 -d 300
# Export results to JSON
uv run python -m tests.load.oauth_benchmark -u 5 -d 120 --output results.json
```
### Advanced Options
```bash
# Sharing-focused workload
uv run python -m tests.load.oauth_benchmark --workload sharing -u 8 -d 180
# Collaborative editing workload
uv run python -m tests.load.oauth_benchmark --workload collaboration -u 6 -d 120
# Baseline operations only (no workflows)
uv run python -m tests.load.oauth_benchmark --workload baseline -u 10 -d 60
# Verbose logging for debugging
uv run python -m tests.load.oauth_benchmark -u 2 -d 30 --verbose
```
### CLI Options
| Option | Short | Default | Description |
|--------|-------|---------|-------------|
| `--users` | `-u` | 2 | Number of concurrent users (dynamically created) |
| `--duration` | `-d` | 30.0 | Test duration in seconds |
| `--warmup` | `-w` | 5.0 | Warmup period before metrics collection (seconds) |
| `--url` | | `http://127.0.0.1:8001/mcp` | MCP OAuth server URL |
| `--output` | `-o` | None | JSON output file path |
| `--workload` | | `mixed` | Workload type: mixed, sharing, collaboration, baseline |
| `--user-prefix` | | `loadtest` | Prefix for dynamically created usernames |
| `--cleanup/--no-cleanup` | | `cleanup` | Delete created users after benchmark |
| `--browser` | | `chromium` | Playwright browser: firefox, chromium, webkit |
| `--headed` | | False | Run browser in headed mode (visible window) |
| `--verbose` | `-v` | False | Enable verbose logging |
## Test User Creation
The framework **dynamically creates test users** on-demand with OAuth authentication:
- **Naming**: Users are created with the pattern `{prefix}_user_{n}` (default: `loadtest_user_1`, `loadtest_user_2`, etc.)
- **Customization**: Use `--user-prefix` to change the prefix (e.g., `--user-prefix mytest` → `mytest_user_1`)
- **Scalability**: No limit on user count - create as many concurrent users as your system can handle
- **Credentials**: Each user gets a randomly generated secure password
- **OAuth Tokens**: All users authenticate via automated OAuth flow using Playwright
- **Cleanup**: Users are automatically deleted after the benchmark (disable with `--no-cleanup`)
**Example**: Running `--users 5` creates:
- `loadtest_user_1` (Display: Load Test User 1, Email: loadtest_user_1@benchmark.local)
- `loadtest_user_2` (Display: Load Test User 2, Email: loadtest_user_2@benchmark.local)
- `loadtest_user_3` (Display: Load Test User 3, Email: loadtest_user_3@benchmark.local)
- `loadtest_user_4` (Display: Load Test User 4, Email: loadtest_user_4@benchmark.local)
- `loadtest_user_5` (Display: Load Test User 5, Email: loadtest_user_5@benchmark.local)
## Metrics Output
### Console Report
```
================================================================================
OAUTH MULTI-USER BENCHMARK RESULTS
================================================================================
Duration: 120.45s
Total Users: 5
Total Workflows Executed: 312
Total Baseline Operations: 678
--------------------------------------------------------------------------------
WORKFLOW STATISTICS
--------------------------------------------------------------------------------
Workflow Total Success Rate P50 P95
--------------------------------------------------------------------------------
note_share 112 109 97.3% 0.2341s 0.4782s
collaborative_edit 65 61 93.8% 0.5123s 0.9234s
file_share 29 29 100.0% 0.3456s 0.6123s
--------------------------------------------------------------------------------
PER-USER STATISTICS
--------------------------------------------------------------------------------
User Total Ops Success Errors Rate P50
--------------------------------------------------------------------------------
loadtest_user_1 289 283 6 97.9% 0.2456s
loadtest_user_2 245 241 4 98.4% 0.2123s
loadtest_user_3 231 226 5 97.8% 0.2345s
loadtest_user_4 198 195 3 98.5% 0.2234s
loadtest_user_5 187 184 3 98.4% 0.2189s
--------------------------------------------------------------------------------
BASELINE OPERATIONS
--------------------------------------------------------------------------------
Total Operations: 678
Success Rate: 98.2%
Latency: min=0.0234s, p50=0.1234s, p95=0.3456s, max=0.8123s
================================================================================
```
### JSON Export
```json
{
"summary": {
"duration": 120.45,
"total_workflows": 312,
"total_baseline_ops": 678,
"total_users": 5
},
"workflows": {
"note_share": {
"total_executions": 112,
"successful_executions": 109,
"failed_executions": 3,
"success_rate": 97.3,
"latency": {
"min": 0.1234,
"max": 0.8765,
"mean": 0.2891,
"median": 0.2341,
"p90": 0.4123,
"p95": 0.4782,
"p99": 0.7234
},
"step_latencies": {
"create_note": {...},
"share_note": {...},
"list_shared_with_me": {...},
"read_shared_note": {...}
}
}
},
"users": {
"loadtest_user_1": {
"total_operations": 289,
"successful_operations": 283,
"failed_operations": 6,
"success_rate": 97.9,
"latency": {...},
"operations_breakdown": {...},
"errors_breakdown": {...}
},
"loadtest_user_2": {...},
"loadtest_user_3": {...},
"loadtest_user_4": {...},
"loadtest_user_5": {...}
},
"baseline": {...}
}
```
## Implementation Status
### ✅ Completed Components
**Framework:**
- OAuth user pool management with dynamic user creation
- User session wrappers with automatic tracking
- Workflow base classes and framework
- 3 example workflows (note share, collaborative edit, file share)
- Enhanced metrics with per-user and workflow tracking
- CLI interface with multiple workload options
- Comprehensive reporting (console + JSON)
**OAuth Integration:**
- ✅ Playwright browser automation for OAuth login
- ✅ OAuth callback server for auth code capture
- ✅ Token exchange with OIDC provider
- ✅ OAuth token injection into MCP sessions via Authorization headers
- ✅ Cancel scope error handling for reliable cleanup
- ✅ Dynamic user creation and deletion via Nextcloud Users API
**Implementation Details:**
The benchmark now successfully:
1. Creates Nextcloud users dynamically with unique passwords
2. Acquires OAuth tokens via automated Playwright browser flows
3. Creates MCP client sessions with proper `Authorization: Bearer {token}` headers
4. Executes coordinated multi-user workflows
5. Tracks per-user and per-workflow metrics
6. Provides standalone cleanup utility for test users
**Key Fix (oauth_pool.py:163-164)**:
```python
# Pass OAuth token as Authorization header
headers = {"Authorization": f"Bearer {profile.token}"}
streamable_context = streamablehttp_client(mcp_url, headers=headers)
```
## Creating Custom Workflows
### Example: Permission Escalation Workflow
```python
class PermissionEscalationWorkflow(Workflow):
"""Test sharing permission changes."""
def __init__(self):
super().__init__("permission_escalation")
async def execute(self, users: list[UserSessionWrapper]) -> WorkflowResult:
self.start_time = time.time()
if len(users) < 2:
return self._finish(False, error="Requires 2+ users")
owner, collaborator = users[0], users[1]
# Step 1: Owner creates note
create_result = await self._execute_step(
"create_note",
owner,
lambda: owner.call_tool("nc_notes_create_note", {...})
)
# Step 2: Share read-only
await self._execute_step(
"share_readonly",
owner,
lambda: owner.call_tool("nc_share_create", {
"permissions": 1 # Read-only
})
)
# Step 3: Upgrade to edit permissions
await self._execute_step(
"upgrade_permissions",
owner,
lambda: owner.call_tool("nc_share_update", {
"permissions": 15 # Read+update+create+delete
})
)
# Step 4: Collaborator edits
await self._execute_step(
"collaborator_edit",
collaborator,
lambda: collaborator.call_tool("nc_notes_update_note", {...})
)
return self._finish(success=True)
```
### Registering Custom Workflows
```python
# In oauth_workloads.py
class MixedOAuthWorkload:
def __init__(self, users: list[UserSessionWrapper]):
self.users = users
self.workflows = {
"note_share": NoteShareWorkflow(),
"collaborative_edit": CollaborativeEditWorkflow(),
"file_share": FileShareAndDownloadWorkflow(),
"permission_escalation": PermissionEscalationWorkflow(), # Add your workflow
}
```
## Performance Expectations
### Baseline Performance (basic auth, from existing benchmarks)
- **Throughput**: 50-200 RPS for mixed workload
- **Latency**: p50 <100ms, p95 <500ms, p99 <1000ms
### OAuth Multi-User Expectations
- **Lower throughput**: ~30-60% of baseline due to:
- OAuth token validation overhead
- Cross-user synchronization delays
- Workflow coordination overhead
- **Higher p99 latency**: Due to workflow step dependencies
- **Focus**: End-to-end workflow completion time more important than raw RPS
### Common Bottlenecks
1. **OAuth token validation**: Per-request overhead
2. **Share propagation**: Time for shares to become visible to recipients
3. **Concurrent edit conflicts**: ETags and conflict resolution
4. **Permission checks**: Cross-user access validation
## Best Practices
1. **Start Small**: Begin with 2-3 users to validate workflows
2. **Monitor Errors**: Watch for permission errors and conflicts
3. **Adjust Delays**: Tune sleep delays between operations based on server response
4. **Profile Workflows**: Use step latencies to identify bottlenecks
5. **Export Results**: Always export to JSON for historical comparison
## Performance Optimizations
### Concurrent User Creation
The benchmark creates and authenticates users **concurrently** for maximum performance:
**Step 5: User Creation & OAuth Authentication**
- All N users are created in parallel using `asyncio.gather()`
- Each user runs through the full OAuth flow simultaneously
- Multiple Playwright browser contexts operate independently
**Step 6: MCP Session Creation**
- All user sessions are created concurrently
- OAuth tokens passed as Authorization headers to each session
**Performance Impact:**
- **Sequential** (old): ~10-12s per user → 40-48s for 4 users
- **Concurrent** (new): ~12-15s total for 4 users (3-4x speedup!)
Example output showing concurrent execution:
```
Step 5/6: Creating 4 users and acquiring OAuth tokens...
(Running concurrently for faster setup)
[1/4] Creating user 'loadtest_user_1'...
[2/4] Creating user 'loadtest_user_2'...
[3/4] Creating user 'loadtest_user_3'...
[4/4] Creating user 'loadtest_user_4'...
✓ User 'loadtest_user_4' authenticated
✓ User 'loadtest_user_2' authenticated
✓ User 'loadtest_user_1' authenticated
✓ User 'loadtest_user_3' authenticated
✓ Successfully created and authenticated 4 users
```
**Implementation** (oauth_benchmark.py:402-437):
```python
# Create tasks for all users
tasks = [
create_user_task(i, browser, callback_server.auth_states)
for i in range(num_users)
]
# Run all concurrently
results = await asyncio.gather(*tasks, return_exceptions=True)
```
## Cleanup
**Important**: Due to asyncio scoping issues with the MCP client library, automatic cleanup in the benchmark's finally block may not execute reliably. Always use the cleanup utility after running benchmarks.
### Cleanup Utility (Recommended)
Use the cleanup utility to remove test users:
```bash
# Dry run - see what would be deleted
uv run python -m tests.load.cleanup_loadtest_users --dry-run
# Delete all loadtest users
uv run python -m tests.load.cleanup_loadtest_users
# Delete users with custom prefix
uv run python -m tests.load.cleanup_loadtest_users --prefix mytest
```
### Disable Automatic Cleanup
To keep test users after the benchmark for inspection:
```bash
uv run python -m tests.load.oauth_benchmark --users 2 --no-cleanup
```
## Troubleshooting
### Leftover Test Users
**Symptom**: Test users remain in Nextcloud after benchmark crashes
**Solution**: Run the cleanup utility:
```bash
uv run python -m tests.load.cleanup_loadtest_users
```
### "User X not in pool" Error
- Ensure user count doesn't exceed configured limits
- Check that user creation succeeded in previous steps
### CancelledError During Benchmark
**Symptom**: Error message like `'CancelledError' object has no attribute 'username'` appears in logs
**Cause**: Async task cancellation during benchmark shutdown or errors can cause race conditions in error handling
**Solution**: This has been mitigated with defensive error handling. The worker now:
- Catches `asyncio.CancelledError` specifically before general exceptions
- Logs cancellation gracefully without attempting to access potentially invalid state
- Re-raises the exception to allow proper cleanup chain
If you still see this error, it's likely harmless and occurs during shutdown. The benchmark results should still be valid.
### High Error Rates
- Increase delay between operations (`await asyncio.sleep()` in worker)
- Check OAuth token validity
- Verify MCP OAuth server is running and accessible (port 8001)
- Rebuild mcp-oauth container after code changes: `docker-compose up --build -d mcp-oauth`
### Workflows Failing
- Check step-by-step latencies to identify failing steps
- Verify users have correct permissions
- Review server logs for errors
### MCP Session Creation Fails (401 Unauthorized)
**Solution**: This issue has been fixed! OAuth tokens are now properly passed as Authorization headers when creating MCP sessions.
If you still see 401 errors:
- Rebuild the mcp-oauth container: `docker-compose up --build -d mcp-oauth`
- Verify OAuth tokens are being acquired successfully in verbose mode
- Check that the token hasn't expired (use shorter test durations during troubleshooting)
## Future Enhancements
- [x] Dynamic user creation (beyond 4 default users) - **COMPLETED**
- [x] OAuth token injection for MCP sessions - **COMPLETED**
- [x] Cancel scope error handling - **COMPLETED**
- [x] Concurrent user creation and authentication - **COMPLETED** (3-4x speedup!)
- [ ] Workflow templates for common patterns
- [ ] Real-time dashboard for live monitoring
- [ ] Historical comparison and regression detection
- [ ] Load ramping (gradual user increase)
- [ ] Geographic distribution simulation (latency injection)
- [ ] Improve cleanup reliability in finally block
tests/load/__init__.py
+1
View File
@@ -0,0 +1 @@
"""Load testing utilities for Nextcloud MCP Server."""
tests/load/benchmark.py
+504
View File
@@ -0,0 +1,504 @@
#!/usr/bin/env python3
"""
Load testing benchmark for Nextcloud MCP Server.
Usage:
uv run python -m tests.load.benchmark --concurrency 10 --duration 30
uv run python -m tests.load.benchmark -c 50 -d 300 --output results.json
"""
import json
import logging
import signal
import statistics
import sys
import time
from collections import Counter
from contextlib import asynccontextmanager
from typing import Any
import anyio
import click
from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client
from tests.load.workloads import MixedWorkload, OperationResult, WorkloadOperations
logging.basicConfig(
level=logging.WARNING, format="%(levelname)s [%(asctime)s] %(name)s - %(message)s"
)
logger = logging.getLogger(__name__)
class BenchmarkMetrics:
"""Collect and analyze benchmark metrics."""
def __init__(self):
self.results: list[OperationResult] = []
self.start_time: float | None = None
self.end_time: float | None = None
self._operation_counts: Counter = Counter()
self._operation_errors: Counter = Counter()
def add_result(self, result: OperationResult):
"""Add a single operation result."""
self.results.append(result)
self._operation_counts[result.operation] += 1
if not result.success:
self._operation_errors[result.operation] += 1
def start(self):
"""Mark the start of the benchmark."""
self.start_time = time.time()
def stop(self):
"""Mark the end of the benchmark."""
self.end_time = time.time()
@property
def duration(self) -> float:
"""Total benchmark duration in seconds."""
if self.start_time is None or self.end_time is None:
return 0.0
return self.end_time - self.start_time
@property
def total_requests(self) -> int:
"""Total number of requests made."""
return len(self.results)
@property
def successful_requests(self) -> int:
"""Number of successful requests."""
return sum(1 for r in self.results if r.success)
@property
def failed_requests(self) -> int:
"""Number of failed requests."""
return sum(1 for r in self.results if not r.success)
@property
def error_rate(self) -> float:
"""Error rate as a percentage."""
if self.total_requests == 0:
return 0.0
return (self.failed_requests / self.total_requests) * 100
@property
def requests_per_second(self) -> float:
"""Average requests per second."""
if self.duration == 0:
return 0.0
return self.total_requests / self.duration
def latency_stats(self) -> dict[str, float]:
"""Calculate latency statistics."""
if not self.results:
return {
"min": 0.0,
"max": 0.0,
"mean": 0.0,
"median": 0.0,
"p90": 0.0,
"p95": 0.0,
"p99": 0.0,
}
durations = [r.duration for r in self.results]
sorted_durations = sorted(durations)
def percentile(data: list[float], p: float) -> float:
k = (len(data) - 1) * p
f = int(k)
c = f + 1
if c >= len(data):
return data[-1]
return data[f] + (k - f) * (data[c] - data[f])
return {
"min": min(durations),
"max": max(durations),
"mean": statistics.mean(durations),
"median": statistics.median(durations),
"p90": percentile(sorted_durations, 0.90),
"p95": percentile(sorted_durations, 0.95),
"p99": percentile(sorted_durations, 0.99),
}
def operation_breakdown(self) -> dict[str, dict[str, Any]]:
"""Get per-operation statistics."""
breakdown = {}
for op_name in self._operation_counts:
op_results = [r for r in self.results if r.operation == op_name]
op_durations = [r.duration for r in op_results if r.success]
if op_durations:
sorted_durations = sorted(op_durations)
p50 = statistics.median(sorted_durations)
p95_idx = int(len(sorted_durations) * 0.95)
p95 = sorted_durations[min(p95_idx, len(sorted_durations) - 1)]
else:
p50 = p95 = 0.0
breakdown[op_name] = {
"count": self._operation_counts[op_name],
"errors": self._operation_errors[op_name],
"success_rate": (
(self._operation_counts[op_name] - self._operation_errors[op_name])
/ self._operation_counts[op_name]
* 100
),
"p50_latency": p50,
"p95_latency": p95,
}
return breakdown
def to_dict(self) -> dict[str, Any]:
"""Convert metrics to dictionary for JSON export."""
return {
"summary": {
"duration": self.duration,
"total_requests": self.total_requests,
"successful_requests": self.successful_requests,
"failed_requests": self.failed_requests,
"error_rate": self.error_rate,
"requests_per_second": self.requests_per_second,
},
"latency": self.latency_stats(),
"operations": self.operation_breakdown(),
}
def print_report(self):
"""Print human-readable benchmark report."""
print("\n" + "=" * 80)
print("BENCHMARK RESULTS")
print("=" * 80)
print(f"\nDuration: {self.duration:.2f}s")
print(f"Total Requests: {self.total_requests}")
print(f"Successful: {self.successful_requests}")
print(f"Failed: {self.failed_requests}")
print(f"Error Rate: {self.error_rate:.2f}%")
print(f"Requests/Second: {self.requests_per_second:.2f}")
print("\n" + "-" * 80)
print("LATENCY (seconds)")
print("-" * 80)
latency = self.latency_stats()
print(f"Min: {latency['min']:.4f}s")
print(f"Mean: {latency['mean']:.4f}s")
print(f"Median: {latency['median']:.4f}s")
print(f"P90: {latency['p90']:.4f}s")
print(f"P95: {latency['p95']:.4f}s")
print(f"P99: {latency['p99']:.4f}s")
print(f"Max: {latency['max']:.4f}s")
print("\n" + "-" * 80)
print("OPERATION BREAKDOWN")
print("-" * 80)
print(
f"{'Operation':<25} {'Count':>8} {'Errors':>8} {'Success':>9} {'P50':>10} {'P95':>10}"
)
print("-" * 80)
breakdown = self.operation_breakdown()
for op_name, stats in sorted(breakdown.items()):
print(
f"{op_name:<25} {stats['count']:>8} {stats['errors']:>8} "
f"{stats['success_rate']:>8.1f}% {stats['p50_latency']:>9.4f}s {stats['p95_latency']:>9.4f}s"
)
print("=" * 80 + "\n")
@asynccontextmanager
async def create_mcp_session(url: str):
"""Create an MCP client session with proper cleanup."""
logger.info(f"Creating MCP client session for {url}")
streamable_context = streamablehttp_client(url)
session_context = None
try:
read_stream, write_stream, _ = await streamable_context.__aenter__()
session_context = ClientSession(read_stream, write_stream)
session = await session_context.__aenter__()
await session.initialize()
logger.info("MCP client session initialized")
yield session
finally:
if session_context is not None:
try:
await session_context.__aexit__(None, None, None)
except Exception as e:
logger.debug(f"Error closing session: {e}")
try:
await streamable_context.__aexit__(None, None, None)
except Exception as e:
logger.debug(f"Error closing streamable context: {e}")
async def wait_for_mcp_server(url: str, max_attempts: int = 10) -> bool:
"""Wait for MCP server to be ready."""
logger.info(f"Waiting for MCP server at {url}...")
for attempt in range(1, max_attempts + 1):
try:
async with create_mcp_session(url) as session:
# Try to get capabilities
await session.read_resource("nc://capabilities")
logger.info("MCP server is ready")
return True
except Exception as e:
if attempt < max_attempts:
logger.debug(f"Attempt {attempt}/{max_attempts}: {e}")
await anyio.sleep(2)
else:
logger.error(f"MCP server not ready after {max_attempts} attempts")
return False
return False
async def benchmark_worker(
worker_id: int,
url: str,
duration: float,
metrics: BenchmarkMetrics,
stop_event: anyio.Event,
):
"""Single worker that runs operations for the specified duration."""
logger.info(f"Worker {worker_id} starting...")
try:
async with create_mcp_session(url) as session:
ops = WorkloadOperations(session)
workload = MixedWorkload(ops)
# Warmup
await workload.warmup(count=5)
# Run operations until duration expires or stop event is set
start_time = time.time()
operation_count = 0
while not stop_event.is_set():
if time.time() - start_time >= duration:
break
result = await workload.run_operation()
metrics.add_result(result)
operation_count += 1
# Small delay to prevent overwhelming the server
await anyio.sleep(0.01)
# Cleanup
await ops.cleanup()
logger.info(f"Worker {worker_id} completed {operation_count} operations")
except Exception as e:
logger.error(f"Worker {worker_id} error: {e}", exc_info=True)
async def run_benchmark(
url: str,
concurrency: int,
duration: float,
warmup: float = 5.0,
) -> BenchmarkMetrics:
"""Run the benchmark with specified parameters."""
metrics = BenchmarkMetrics()
stop_event = anyio.Event()
# Setup signal handlers for graceful shutdown
def signal_handler(sig, frame):
logger.warning("Received interrupt signal, stopping benchmark...")
stop_event.set()
signal.signal(signal.SIGINT, signal_handler)
signal.signal(signal.SIGTERM, signal_handler)
print(
f"\nStarting benchmark with {concurrency} concurrent workers for {duration}s..."
)
print(f"Target: {url}")
print(f"Warmup period: {warmup}s\n")
# Warmup period
if warmup > 0:
print("Warming up...")
await anyio.sleep(warmup)
# Start metrics collection
metrics.start()
# Create and run workers using anyio task groups
async with anyio.create_task_group() as tg:
# Start all workers
for i in range(concurrency):
tg.start_soon(benchmark_worker, i, url, duration, metrics, stop_event)
# Show progress
tg.start_soon(show_progress, duration, metrics, stop_event)
# Stop metrics (tasks already completed when task group exits)
metrics.stop()
return metrics
async def show_progress(
duration: float,
metrics: BenchmarkMetrics,
stop_event: anyio.Event,
):
"""Show real-time progress during benchmark."""
start_time = time.time()
while not stop_event.is_set():
elapsed = time.time() - start_time
if elapsed >= duration:
break
# Calculate progress
progress = min(elapsed / duration * 100, 100)
rps = metrics.total_requests / max(elapsed, 0.1)
# Print progress bar
bar_length = 40
filled = int(bar_length * progress / 100)
bar = "█" * filled + "░" * (bar_length - filled)
print(
f"\r[{bar}] {progress:5.1f}% | "
f"Requests: {metrics.total_requests:6d} | "
f"RPS: {rps:6.1f} | "
f"Errors: {metrics.failed_requests:4d}",
end="",
flush=True,
)
await anyio.sleep(0.5)
print() # New line after progress
@click.command()
@click.option(
"--concurrency",
"-c",
type=int,
default=10,
show_default=True,
help="Number of concurrent workers",
)
@click.option(
"--duration",
"-d",
type=float,
default=30.0,
show_default=True,
help="Test duration in seconds",
)
@click.option(
"--warmup",
"-w",
type=float,
default=5.0,
show_default=True,
help="Warmup duration before collecting metrics (seconds)",
)
@click.option(
"--url",
"-u",
default="http://127.0.0.1:8000/mcp",
show_default=True,
help="MCP server URL",
)
@click.option(
"--output",
"-o",
type=click.Path(),
help="Output file for JSON results (optional)",
)
@click.option(
"--wait-for-server/--no-wait",
default=True,
show_default=True,
help="Wait for MCP server to be ready before starting",
)
@click.option(
"--verbose",
"-v",
is_flag=True,
help="Enable verbose logging",
)
def main(
concurrency: int,
duration: float,
warmup: float,
url: str,
output: str | None,
wait_for_server: bool,
verbose: bool,
):
"""
Load testing benchmark for Nextcloud MCP Server.
Runs a mixed workload of realistic MCP operations against the server
and reports detailed performance metrics.
Examples:
# Quick 30-second test with 10 workers
uv run python -m tests.load.benchmark --concurrency 10 --duration 30
# Extended test with 50 workers for 5 minutes
uv run python -m tests.load.benchmark -c 50 -d 300
# Export results to JSON
uv run python -m tests.load.benchmark -c 20 -d 60 --output results.json
# Test OAuth server on port 8001
uv run python -m tests.load.benchmark --url http://127.0.0.1:8001/mcp
"""
if verbose:
logging.getLogger().setLevel(logging.DEBUG)
logging.getLogger("tests.load").setLevel(logging.DEBUG)
async def run():
# Wait for server if requested
if wait_for_server:
if not await wait_for_mcp_server(url):
print("ERROR: MCP server is not ready", file=sys.stderr)
sys.exit(1)
# Run benchmark
metrics = await run_benchmark(url, concurrency, duration, warmup)
# Print report
metrics.print_report()
# Export to JSON if requested
if output:
with open(output, "w") as f:
json.dump(metrics.to_dict(), f, indent=2)
print(f"Results exported to: {output}")
try:
anyio.run(run)
except KeyboardInterrupt:
print("\nBenchmark interrupted by user")
sys.exit(130)
except Exception as e:
print(f"ERROR: {e}", file=sys.stderr)
if verbose:
raise
sys.exit(1)
if __name__ == "__main__":
main()
tests/load/cleanup_loadtest_users.py
+117
View File
@@ -0,0 +1,117 @@
#!/usr/bin/env python3
"""
Cleanup utility for loadtest users.
Searches for and deletes all users with 'loadtest' prefix in their username.
Useful for cleaning up after failed benchmark runs.
Usage:
uv run python -m tests.load.cleanup_loadtest_users
uv run python -m tests.load.cleanup_loadtest_users --prefix mytest
uv run python -m tests.load.cleanup_loadtest_users --dry-run
"""
import sys
import anyio
import click
from nextcloud_mcp_server.client import NextcloudClient
async def cleanup_users(prefix: str = "loadtest", dry_run: bool = False):
"""
Search for and delete users with the specified prefix.
Args:
prefix: Username prefix to search for
dry_run: If True, only list users without deleting them
"""
print(f"Searching for users with prefix '{prefix}'...")
try:
client = NextcloudClient.from_env()
users = await client.users.search_users(search=prefix)
if not users:
print(f"✓ No users found with prefix '{prefix}'")
return
print(f"Found {len(users)} user(s): {', '.join(users)}\n")
if dry_run:
print("DRY RUN - No users will be deleted")
for user in users:
print(f" Would delete: {user}")
print("\nTo actually delete these users, run without --dry-run flag")
return
# Delete users
deleted = []
failed = []
for user in users:
try:
print(f" Deleting {user}...")
await client.users.delete_user(userid=user)
deleted.append(user)
print(f" ✓ Deleted {user}")
except Exception as e:
failed.append((user, str(e)))
print(f" ✗ Failed to delete {user}: {e}")
# Summary
print(f"\n{'=' * 60}")
print("Cleanup Summary")
print(f"{'=' * 60}")
print(f"Successfully deleted: {len(deleted)}")
print(f"Failed to delete: {len(failed)}")
if failed:
print("\nFailed deletions:")
for user, error in failed:
print(f" - {user}: {error}")
sys.exit(1)
else:
print("\n✓ All users cleaned up successfully")
except Exception as e:
print(f"ERROR: {e}", file=sys.stderr)
sys.exit(1)
@click.command()
@click.option(
"--prefix",
default="loadtest",
show_default=True,
help="Username prefix to search for",
)
@click.option(
"--dry-run",
is_flag=True,
help="List users without deleting them",
)
def main(prefix: str, dry_run: bool):
"""
Cleanup loadtest users from Nextcloud.
Searches for all users with the specified prefix and deletes them.
Useful for cleaning up after failed benchmark runs.
Examples:
# Dry run to see what would be deleted
uv run python -m tests.load.cleanup_loadtest_users --dry-run
# Delete all loadtest users
uv run python -m tests.load.cleanup_loadtest_users
# Delete users with custom prefix
uv run python -m tests.load.cleanup_loadtest_users --prefix mytest
"""
anyio.run(cleanup_users, prefix, dry_run)
if __name__ == "__main__":
main()
tests/load/oauth_benchmark.py
+768
View File
@@ -0,0 +1,768 @@
#!/usr/bin/env python3
"""
OAuth Multi-User Load Testing for Nextcloud MCP Server.
Simulates realistic multi-user scenarios with coordinated workflows
like note sharing, collaborative editing, and file operations.
Usage:
uv run python -m tests.load.oauth_benchmark --users 4 --duration 60
uv run python -m tests.load.oauth_benchmark -u 10 -d 300 --workload sharing
"""
import json
import logging
import os
import secrets
import signal
import sys
import threading
import time
from http.server import BaseHTTPRequestHandler, HTTPServer
from typing import Any
from urllib.parse import parse_qs, urlparse
import anyio
import click
import httpx
from playwright.async_api import async_playwright
from nextcloud_mcp_server.auth.client_registration import load_or_register_client
from nextcloud_mcp_server.client import NextcloudClient
from tests.load.oauth_metrics import OAuthBenchmarkMetrics
from tests.load.oauth_pool import (
OAuthUserPool,
UserSessionWrapper,
generate_secure_password,
)
from tests.load.oauth_workloads import MixedOAuthWorkload, WorkflowResult
logging.basicConfig(
level=logging.WARNING, format="%(levelname)s [%(asctime)s] %(name)s - %(message)s"
)
logger = logging.getLogger(__name__)
class OAuthCallbackServer:
"""
Temporary HTTP server to capture OAuth authorization codes.
Runs in a background thread, captures auth codes via state parameter
correlation, and stores them in a shared dictionary.
"""
def __init__(self, host: str = "127.0.0.1", port: int = 8081):
self.host = host
self.port = port
self.auth_states: dict[str, str] = {}
self.server: HTTPServer | None = None
self.thread: threading.Thread | None = None
def start(self):
"""Start the callback server in a background thread."""
class CallbackHandler(BaseHTTPRequestHandler):
auth_states = self.auth_states
def do_GET(self):
parsed = urlparse(self.path)
if parsed.path == "/callback":
params = parse_qs(parsed.query)
code = params.get("code", [None])[0]
state = params.get("state", [None])[0]
if code and state:
self.auth_states[state] = code
logger.info(f"Captured auth code for state {state[:16]}...")
self.send_response(200)
self.send_header("Content-type", "text/html")
self.end_headers()
self.wfile.write(
b"<html><body><h1>Authorization successful!</h1>"
b"<p>You can close this window.</p></body></html>"
)
else:
self.send_response(404)
self.end_headers()
def log_message(self, format, *args):
# Suppress default logging
pass
self.server = HTTPServer((self.host, self.port), CallbackHandler)
def run():
logger.info(f"OAuth callback server listening on {self.host}:{self.port}")
self.server.serve_forever()
self.thread = threading.Thread(target=run, daemon=True)
self.thread.start()
logger.info("OAuth callback server started")
def stop(self):
"""Stop the callback server."""
if self.server:
self.server.shutdown()
logger.info("OAuth callback server stopped")
def get_auth_code(self, state: str) -> str | None:
"""Get auth code for a given state parameter."""
return self.auth_states.get(state)
async def discover_oidc_endpoints(nextcloud_host: str) -> dict[str, str]:
"""
Discover OIDC endpoints from Nextcloud's .well-known configuration.
Args:
nextcloud_host: Nextcloud host URL (e.g., http://localhost:8080)
Returns:
Dict with authorization_endpoint, token_endpoint, and registration_endpoint
"""
logger.info("Discovering OIDC endpoints...")
async with httpx.AsyncClient(verify=False, timeout=30.0) as client:
response = await client.get(
f"{nextcloud_host}/.well-known/openid-configuration"
)
response.raise_for_status()
config = response.json()
endpoints = {
"authorization_endpoint": config["authorization_endpoint"],
"token_endpoint": config["token_endpoint"],
"registration_endpoint": config["registration_endpoint"],
}
logger.info(f"Discovered endpoints: {endpoints}")
return endpoints
async def setup_oauth_client(
nextcloud_host: str, callback_url: str, registration_endpoint: str
) -> dict[str, str]:
"""
Setup OAuth client using load_or_register_client.
Args:
nextcloud_host: Nextcloud host URL
callback_url: OAuth callback URL
registration_endpoint: OAuth registration endpoint URL
Returns:
Dict with client_id and client_secret
"""
logger.info("Setting up OAuth client...")
# Use the client registration utility
client_info = await load_or_register_client(
nextcloud_url=nextcloud_host,
registration_endpoint=registration_endpoint,
storage_path=".nextcloud_oauth_benchmark_client.json",
client_name="OAuth Benchmark Test Client",
redirect_uris=[callback_url],
)
logger.info(f"OAuth client setup complete (client_id: {client_info.client_id})")
return {
"client_id": client_info.client_id,
"client_secret": client_info.client_secret,
}
async def create_and_authenticate_user(
user_pool: OAuthUserPool,
browser: Any,
auth_states: dict[str, str],
username: str,
password: str,
display_name: str | None = None,
) -> str:
"""
Create Nextcloud user and acquire OAuth token via Playwright.
Args:
user_pool: OAuthUserPool instance
browser: Playwright browser instance
auth_states: Shared auth_states dict for callback server
username: Username to create
password: Password for the user
display_name: Optional display name
Returns:
OAuth access token for the user
"""
logger.info(f"Creating and authenticating user: {username}")
# Create Nextcloud user
await user_pool.create_nextcloud_user(
username=username,
password=password,
display_name=display_name or username,
)
# Generate unique state for this OAuth flow
state = secrets.token_urlsafe(32)
# Acquire OAuth token via Playwright
token = await user_pool.acquire_token_playwright(
browser=browser,
username=username,
password=password,
state=state,
auth_states=auth_states,
)
logger.info(f"Successfully authenticated user: {username}")
return token
async def oauth_benchmark_worker(
user_wrapper: UserSessionWrapper,
workload: MixedOAuthWorkload,
duration: float,
metrics: OAuthBenchmarkMetrics,
stop_event: anyio.Event,
):
"""
Single worker executing operations for one user.
Args:
user_wrapper: UserSessionWrapper for this worker
workload: MixedOAuthWorkload instance
duration: Test duration in seconds
metrics: Metrics collector
stop_event: Event to signal stop
"""
logger.info(f"Worker for {user_wrapper.username} starting...")
start_time = time.time()
operation_count = 0
try:
while not stop_event.is_set():
if time.time() - start_time >= duration:
break
# Run an operation (might be baseline or workflow)
result = await workload.run_operation()
# Record metrics
if isinstance(result, WorkflowResult):
metrics.add_workflow_result(result)
else:
# Baseline operation
metrics.add_baseline_operation(result)
operation_count += 1
# Small delay to prevent overwhelming the server
await anyio.sleep(0.05)
logger.info(
f"Worker for {user_wrapper.username} completed {operation_count} operations"
)
except anyio.get_cancelled_exc_class():
# Handle task cancellation gracefully (e.g., during benchmark shutdown)
logger.info(
f"Worker for {user_wrapper.username} was cancelled "
f"(completed {operation_count} operations)"
)
raise # Re-raise to allow proper cleanup
except Exception as e:
logger.error(f"Worker {user_wrapper.username} error: {e}", exc_info=True)
async def show_progress(
duration: float,
metrics: OAuthBenchmarkMetrics,
stop_event: anyio.Event,
):
"""Show real-time progress during benchmark."""
start_time = time.time()
while not stop_event.is_set():
elapsed = time.time() - start_time
if elapsed >= duration:
break
# Calculate progress
progress = min(elapsed / duration * 100, 100)
total_ops = len(metrics.baseline_operations) + len(metrics.workflows)
workflows = len(metrics.workflows)
# Print progress bar
bar_length = 40
filled = int(bar_length * progress / 100)
bar = "█" * filled + "░" * (bar_length - filled)
print(
f"\r[{bar}] {progress:5.1f}% | "
f"Total Ops: {total_ops:6d} | "
f"Workflows: {workflows:4d}",
end="",
flush=True,
)
await anyio.sleep(0.5)
print() # New line after progress
async def run_oauth_benchmark(
num_users: int,
duration: float,
mcp_url: str,
warmup: float = 5.0,
user_prefix: str = "loadtest",
cleanup: bool = True,
browser_type: str = "firefox",
headed: bool = False,
) -> OAuthBenchmarkMetrics:
"""
Run the OAuth multi-user benchmark with dynamic user creation.
Args:
num_users: Number of concurrent users to create
duration: Test duration in seconds
mcp_url: MCP server URL
warmup: Warmup period in seconds
user_prefix: Prefix for generated usernames
cleanup: Whether to delete users after benchmark
browser_type: Playwright browser type (firefox, chromium, webkit)
headed: Whether to run browser in headed mode
Returns:
OAuthBenchmarkMetrics with results
"""
metrics = OAuthBenchmarkMetrics()
stop_event = anyio.Event()
created_users: list[str] = []
callback_server: OAuthCallbackServer | None = None
user_pool: OAuthUserPool | None = None
admin_client: NextcloudClient | None = None
# Setup signal handlers for graceful shutdown
def signal_handler(sig, frame):
logger.warning("Received interrupt signal, stopping benchmark...")
stop_event.set()
signal.signal(signal.SIGINT, signal_handler)
signal.signal(signal.SIGTERM, signal_handler)
print(f"\n{'=' * 80}")
print("OAUTH MULTI-USER BENCHMARK")
print(f"{'=' * 80}")
print(f"Users: {num_users} | Duration: {duration}s | Warmup: {warmup}s")
print(f"Target: {mcp_url}")
print(f"User Prefix: {user_prefix} | Cleanup: {cleanup}")
print(f"Browser: {browser_type} | Headed: {headed}")
print(f"{'=' * 80}\n")
try:
# Get environment variables
nextcloud_host = os.getenv("NEXTCLOUD_HOST", "http://localhost:8080")
callback_url = "http://127.0.0.1:8081/callback"
# Step 1: Start OAuth callback server
print("Step 1/6: Starting OAuth callback server...")
callback_server = OAuthCallbackServer(host="127.0.0.1", port=8081)
callback_server.start()
print("✓ Callback server listening on http://127.0.0.1:8081\n")
# Step 2: Discover OIDC endpoints
print("Step 2/6: Discovering OIDC endpoints...")
endpoints = await discover_oidc_endpoints(nextcloud_host)
print(f"✓ Authorization endpoint: {endpoints['authorization_endpoint']}")
print(f"✓ Token endpoint: {endpoints['token_endpoint']}")
print(f"✓ Registration endpoint: {endpoints['registration_endpoint']}\n")
# Step 3: Setup OAuth client
print("Step 3/6: Setting up OAuth client...")
oauth_credentials = await setup_oauth_client(
nextcloud_host, callback_url, endpoints["registration_endpoint"]
)
print(f"✓ OAuth client registered (ID: {oauth_credentials['client_id']})\n")
# Step 4: Create admin client and user pool
print("Step 4/6: Initializing admin client and user pool...")
admin_client = NextcloudClient.from_env()
user_pool = OAuthUserPool(
admin_client=admin_client,
client_id=oauth_credentials["client_id"],
client_secret=oauth_credentials["client_secret"],
callback_url=callback_url,
token_endpoint=endpoints["token_endpoint"],
authorization_endpoint=endpoints["authorization_endpoint"],
)
async with user_pool:
print("✓ User pool initialized\n")
# Step 5: Create users and acquire OAuth tokens (concurrently)
print(f"Step 5/6: Creating {num_users} users and acquiring OAuth tokens...")
print("(Running concurrently for faster setup)\n")
async def create_user_task(
i: int, browser, auth_states: dict
) -> tuple[str, str, str] | None:
"""Create and authenticate a single user. Returns (username, password, token) or None on failure."""
username = f"{user_prefix}_user_{i + 1}"
password = generate_secure_password(16)
print(f" [{i + 1}/{num_users}] Creating user '{username}'...")
try:
token = await create_and_authenticate_user(
user_pool=user_pool,
browser=browser,
auth_states=auth_states,
username=username,
password=password,
display_name=f"Load Test User {i + 1}",
)
print(f" ✓ User '{username}' authenticated\n")
return (username, password, token)
except Exception as e:
logger.error(f"Failed to create/authenticate user {username}: {e}")
return None
async with async_playwright() as p:
# Launch browser
browser_launcher = getattr(p, browser_type)
browser = await browser_launcher.launch(headless=not headed)
try:
# Create all users concurrently using anyio task groups
results = []
async def run_and_collect(i: int):
"""Wrapper to collect results from tasks."""
try:
result = await create_user_task(
i, browser, callback_server.auth_states
)
results.append(result)
except Exception as e:
logger.error(f"User creation task failed: {e}")
results.append(e)
async with anyio.create_task_group() as tg:
for i in range(num_users):
tg.start_soon(run_and_collect, i)
# Process results
for result in results:
if isinstance(result, Exception):
logger.error(f"User creation task failed: {result}")
continue
if result is None:
continue
username, password, token = result
await user_pool.add_user(
username=username, password=password, token=token
)
created_users.append(username)
finally:
await browser.close()
if not created_users:
raise RuntimeError("Failed to create any users")
print(
f"✓ Successfully created and authenticated {len(created_users)} users\n"
)
# Step 6: Create MCP sessions for each user (concurrently)
print("Step 6/6: Creating MCP sessions for users...")
user_wrappers = []
async with user_pool:
async def create_session_task(username: str) -> UserSessionWrapper | None:
"""Create MCP session for a user. Returns wrapper or None on failure."""
try:
session = await user_pool.create_user_session(username, mcp_url)
wrapper = UserSessionWrapper(username, session, user_pool)
print(f" ✓ Session created for '{username}'")
return wrapper
except Exception as e:
logger.error(f"Failed to create session for {username}: {e}")
return None
# Create all sessions concurrently using anyio task groups
session_results = []
async def run_and_collect_session(username: str):
"""Wrapper to collect session results from tasks."""
try:
result = await create_session_task(username)
session_results.append(result)
except Exception as e:
logger.error(f"Session creation task failed: {e}")
session_results.append(e)
async with anyio.create_task_group() as tg:
for username in created_users:
tg.start_soon(run_and_collect_session, username)
# Process results
for result in session_results:
if isinstance(result, Exception):
logger.error(f"Session creation task failed: {result}")
continue
if result is not None:
user_wrappers.append(result)
if not user_wrappers:
raise RuntimeError("Failed to create any user sessions")
print(f"✓ Created {len(user_wrappers)} MCP sessions\n")
# Warmup period
if warmup > 0:
print(f"Warmup period: {warmup}s...")
await anyio.sleep(warmup)
print()
# Start benchmark
print(f"{'=' * 80}")
print("STARTING BENCHMARK")
print(f"{'=' * 80}\n")
metrics.start()
# Create workload and workers using anyio task groups
workload = MixedOAuthWorkload(user_wrappers)
# Run workers with progress display
async with anyio.create_task_group() as tg:
# Start all workers
for wrapper in user_wrappers:
tg.start_soon(
oauth_benchmark_worker,
wrapper,
workload,
duration,
metrics,
stop_event,
)
# Show progress
tg.start_soon(show_progress, duration, metrics, stop_event)
# Tasks already completed when task group exits
metrics.stop()
print(f"\n{'=' * 80}")
print("BENCHMARK COMPLETE")
print(f"{'=' * 80}\n")
# Cleanup user sessions
print("Closing user sessions...")
await user_pool.close_all_sessions()
print("✓ All sessions closed\n")
except Exception as e:
logger.error(f"Benchmark error: {e}", exc_info=True)
# Don't re-raise here - we want cleanup to run
finally:
# Cleanup callback server
if callback_server:
try:
callback_server.stop()
logger.info("OAuth callback server stopped")
except Exception as e:
logger.warning(f"Error stopping callback server: {e}")
# Cleanup test users
if cleanup and created_users:
print(f"\nCleaning up {len(created_users)} test users...")
# Create a new admin client for cleanup (don't rely on the existing one)
try:
cleanup_client = NextcloudClient.from_env()
for username in created_users:
try:
await cleanup_client.users.delete_user(userid=username)
print(f" ✓ Deleted user '{username}'")
except Exception as e:
logger.warning(f"Failed to delete user {username}: {e}")
print("✓ Cleanup complete\n")
except Exception as e:
logger.error(f"Error during user cleanup: {e}")
print(
"⚠️ Failed to cleanup users. Please run cleanup script manually.\n"
)
elif created_users:
print(
f"\n⚠️ {len(created_users)} test users were NOT deleted (cleanup=False)"
)
print(f"Users: {', '.join(created_users)}\n")
return metrics
@click.command()
@click.option(
"--users",
"-u",
type=int,
default=2,
show_default=True,
help="Number of concurrent users to create dynamically",
)
@click.option(
"--duration",
"-d",
type=float,
default=30.0,
show_default=True,
help="Test duration in seconds",
)
@click.option(
"--warmup",
"-w",
type=float,
default=5.0,
show_default=True,
help="Warmup duration before collecting metrics (seconds)",
)
@click.option(
"--url",
default="http://127.0.0.1:8001/mcp",
show_default=True,
help="MCP OAuth server URL",
)
@click.option(
"--output",
"-o",
type=click.Path(),
help="Output file for JSON results (optional)",
)
@click.option(
"--workload",
type=click.Choice(["mixed", "sharing", "collaboration", "baseline"]),
default="mixed",
show_default=True,
help="Workload type to execute",
)
@click.option(
"--user-prefix",
default="loadtest",
show_default=True,
help="Prefix for dynamically created usernames",
)
@click.option(
"--cleanup/--no-cleanup",
default=True,
show_default=True,
help="Delete created users after benchmark",
)
@click.option(
"--browser",
type=click.Choice(["firefox", "chromium", "webkit"]),
default="firefox",
show_default=True,
help="Playwright browser type for OAuth automation",
)
@click.option(
"--headed",
is_flag=True,
help="Run browser in headed mode (visible window, useful for debugging)",
)
@click.option(
"--verbose",
"-v",
is_flag=True,
help="Enable verbose logging",
)
def main(
users: int,
duration: float,
warmup: float,
url: str,
output: str | None,
workload: str,
user_prefix: str,
cleanup: bool,
browser: str,
headed: bool,
verbose: bool,
):
"""
OAuth Multi-User Load Testing for Nextcloud MCP Server.
Dynamically creates N users, authenticates them via OAuth using Playwright
browser automation, and simulates realistic multi-user scenarios with
coordinated workflows like note sharing, collaborative editing, and file operations.
Examples:
# 2 users, 30-second test (default settings)
uv run python -m tests.load.oauth_benchmark
# 4 users, 60-second test with mixed workload
uv run python -m tests.load.oauth_benchmark --users 4 --duration 60
# 10 users, 5-minute sharing-focused test
uv run python -m tests.load.oauth_benchmark -u 10 -d 300 --workload sharing
# Export results to JSON
uv run python -m tests.load.oauth_benchmark -u 5 -d 120 --output results.json
# Custom user prefix and keep users after benchmark
uv run python -m tests.load.oauth_benchmark -u 3 --user-prefix mytest --no-cleanup
# Debug with visible browser (headed mode)
uv run python -m tests.load.oauth_benchmark -u 2 -d 10 --headed --verbose
Requirements:
- docker-compose up (mcp-oauth container running on port 8001)
- NEXTCLOUD_HOST, NEXTCLOUD_USERNAME, NEXTCLOUD_PASSWORD env vars set
- Playwright browser installed: uv run playwright install firefox
"""
if verbose:
logging.getLogger().setLevel(logging.DEBUG)
logging.getLogger("tests.load").setLevel(logging.DEBUG)
async def run():
# Run benchmark
metrics = await run_oauth_benchmark(
num_users=users,
duration=duration,
mcp_url=url,
warmup=warmup,
user_prefix=user_prefix,
cleanup=cleanup,
browser_type=browser,
headed=headed,
)
# Print report
metrics.print_report()
# Export to JSON if requested
if output:
with open(output, "w") as f:
json.dump(metrics.to_dict(), f, indent=2)
print(f"Results exported to: {output}")
try:
anyio.run(run)
except KeyboardInterrupt:
print("\nBenchmark interrupted by user")
sys.exit(130)
except Exception as e:
print(f"ERROR: {e}", file=sys.stderr)
if verbose:
raise
sys.exit(1)
if __name__ == "__main__":
main()
tests/load/oauth_metrics.py
+329
View File
@@ -0,0 +1,329 @@
"""
Enhanced metrics collection for OAuth multi-user load testing.
Extends the base BenchmarkMetrics to track per-user statistics,
workflow completion rates, and cross-user operation latencies.
"""
import statistics
from collections import Counter, defaultdict
from typing import Any
from tests.load.oauth_workloads import WorkflowResult
class OAuthBenchmarkMetrics:
"""
Enhanced metrics for OAuth multi-user load testing.
Tracks:
- Per-user operation counts and latencies
- Workflow completion rates and timings
- Cross-user operation metrics
- Step-by-step workflow breakdowns
"""
def __init__(self):
# Base metrics
self.start_time: float | None = None
self.end_time: float | None = None
# Per-user tracking
self.user_operations: dict[str, list[dict[str, Any]]] = defaultdict(list)
self.user_operation_counts: dict[str, Counter] = defaultdict(Counter)
self.user_errors: dict[str, Counter] = defaultdict(Counter)
# Workflow tracking
self.workflows: list[WorkflowResult] = []
self.workflow_counts: Counter = Counter()
self.workflow_successes: Counter = Counter()
self.workflow_durations: dict[str, list[float]] = defaultdict(list)
# Baseline operations (non-workflow)
self.baseline_operations: list[dict[str, Any]] = []
def start(self):
"""Mark the start of the benchmark."""
import time
self.start_time = time.time()
def stop(self):
"""Mark the end of the benchmark."""
import time
self.end_time = time.time()
@property
def duration(self) -> float:
"""Total benchmark duration in seconds."""
if self.start_time is None or self.end_time is None:
return 0.0
return self.end_time - self.start_time
def add_workflow_result(self, result: WorkflowResult):
"""
Add a workflow execution result.
Args:
result: WorkflowResult from workflow execution
"""
self.workflows.append(result)
self.workflow_counts[result.workflow_name] += 1
if result.success:
self.workflow_successes[result.workflow_name] += 1
self.workflow_durations[result.workflow_name].append(result.total_duration)
# Track per-user operations from workflow steps
for step in result.steps:
self.user_operation_counts[step.user][step.step_name] += 1
if not step.success:
self.user_errors[step.user][step.step_name] += 1
self.user_operations[step.user].append(
{
"type": "workflow_step",
"workflow": result.workflow_name,
"step": step.step_name,
"success": step.success,
"duration": step.duration,
"error": step.error,
}
)
def add_baseline_operation(self, operation: dict[str, Any]):
"""
Add a baseline (non-workflow) operation result.
Args:
operation: Dict with keys: type, operation, user, success, duration, error (optional)
"""
self.baseline_operations.append(operation)
user = operation.get("user", "unknown")
op_name = operation.get("operation", "unknown")
success = operation.get("success", False)
self.user_operation_counts[user][op_name] += 1
if not success:
self.user_errors[user][op_name] += 1
self.user_operations[user].append(operation)
def get_user_stats(self) -> dict[str, dict[str, Any]]:
"""
Get per-user statistics.
Returns:
Dict mapping username to their stats
"""
stats = {}
for user, operations in self.user_operations.items():
total_ops = len(operations)
successful_ops = sum(1 for op in operations if op.get("success", False))
durations = [op["duration"] for op in operations if "duration" in op]
stats[user] = {
"total_operations": total_ops,
"successful_operations": successful_ops,
"failed_operations": total_ops - successful_ops,
"success_rate": (successful_ops / total_ops * 100)
if total_ops > 0
else 0.0,
"latency": self._calculate_latency_stats(durations),
"operations_breakdown": dict(self.user_operation_counts[user]),
"errors_breakdown": dict(self.user_errors[user]),
}
return stats
def get_workflow_stats(self) -> dict[str, dict[str, Any]]:
"""
Get workflow execution statistics.
Returns:
Dict mapping workflow name to its stats
"""
stats = {}
for workflow_name in self.workflow_counts:
total = self.workflow_counts[workflow_name]
successes = self.workflow_successes[workflow_name]
durations = self.workflow_durations[workflow_name]
# Calculate per-step latencies
step_latencies = defaultdict(list)
for workflow in self.workflows:
if workflow.workflow_name == workflow_name:
for step in workflow.steps:
if step.success:
step_latencies[step.step_name].append(step.duration)
step_stats = {}
for step_name, latencies in step_latencies.items():
if latencies:
step_stats[step_name] = self._calculate_latency_stats(latencies)
stats[workflow_name] = {
"total_executions": total,
"successful_executions": successes,
"failed_executions": total - successes,
"success_rate": (successes / total * 100) if total > 0 else 0.0,
"latency": self._calculate_latency_stats(durations),
"step_latencies": step_stats,
}
return stats
def get_baseline_stats(self) -> dict[str, Any]:
"""
Get statistics for baseline operations.
Returns:
Dict with baseline operation stats
"""
if not self.baseline_operations:
return {
"total_operations": 0,
"success_rate": 0.0,
"latency": self._calculate_latency_stats([]),
}
total = len(self.baseline_operations)
successes = sum(
1 for op in self.baseline_operations if op.get("success", False)
)
durations = [
op["duration"] for op in self.baseline_operations if "duration" in op
]
# Per-operation breakdown
operation_counts = Counter()
operation_errors = Counter()
for op in self.baseline_operations:
op_name = op.get("operation", "unknown")
operation_counts[op_name] += 1
if not op.get("success", False):
operation_errors[op_name] += 1
return {
"total_operations": total,
"successful_operations": successes,
"failed_operations": total - successes,
"success_rate": (successes / total * 100) if total > 0 else 0.0,
"latency": self._calculate_latency_stats(durations),
"operations_breakdown": dict(operation_counts),
"errors_breakdown": dict(operation_errors),
}
def _calculate_latency_stats(self, durations: list[float]) -> dict[str, float]:
"""Calculate latency statistics from a list of durations."""
if not durations:
return {
"min": 0.0,
"max": 0.0,
"mean": 0.0,
"median": 0.0,
"p90": 0.0,
"p95": 0.0,
"p99": 0.0,
}
sorted_durations = sorted(durations)
def percentile(data: list[float], p: float) -> float:
k = (len(data) - 1) * p
f = int(k)
c = f + 1
if c >= len(data):
return data[-1]
return data[f] + (k - f) * (data[c] - data[f])
return {
"min": min(durations),
"max": max(durations),
"mean": statistics.mean(durations),
"median": statistics.median(durations),
"p90": percentile(sorted_durations, 0.90),
"p95": percentile(sorted_durations, 0.95),
"p99": percentile(sorted_durations, 0.99),
}
def to_dict(self) -> dict[str, Any]:
"""Convert metrics to dictionary for JSON export."""
return {
"summary": {
"duration": self.duration,
"total_workflows": len(self.workflows),
"total_baseline_ops": len(self.baseline_operations),
"total_users": len(self.user_operations),
},
"workflows": self.get_workflow_stats(),
"baseline": self.get_baseline_stats(),
"users": self.get_user_stats(),
}
def print_report(self):
"""Print human-readable benchmark report."""
print("\n" + "=" * 80)
print("OAUTH MULTI-USER BENCHMARK RESULTS")
print("=" * 80)
# Summary
print(f"\nDuration: {self.duration:.2f}s")
print(f"Total Users: {len(self.user_operations)}")
print(f"Total Workflows Executed: {len(self.workflows)}")
print(f"Total Baseline Operations: {len(self.baseline_operations)}")
# Workflow Stats
if self.workflows:
print("\n" + "-" * 80)
print("WORKFLOW STATISTICS")
print("-" * 80)
print(
f"{'Workflow':<30} {'Total':>8} {'Success':>8} {'Rate':>8} {'P50':>10} {'P95':>10}"
)
print("-" * 80)
workflow_stats = self.get_workflow_stats()
for name, stats in sorted(workflow_stats.items()):
latency = stats["latency"]
print(
f"{name:<30} {stats['total_executions']:>8} "
f"{stats['successful_executions']:>8} "
f"{stats['success_rate']:>7.1f}% "
f"{latency['median']:>9.4f}s {latency['p95']:>9.4f}s"
)
# Per-User Stats
print("\n" + "-" * 80)
print("PER-USER STATISTICS")
print("-" * 80)
print(
f"{'User':<20} {'Total Ops':>10} {'Success':>10} {'Errors':>8} {'Rate':>8} {'P50':>10}"
)
print("-" * 80)
user_stats = self.get_user_stats()
for username, stats in sorted(user_stats.items()):
latency = stats["latency"]
print(
f"{username:<20} {stats['total_operations']:>10} "
f"{stats['successful_operations']:>10} "
f"{stats['failed_operations']:>8} "
f"{stats['success_rate']:>7.1f}% "
f"{latency['median']:>9.4f}s"
)
# Baseline Stats
if self.baseline_operations:
print("\n" + "-" * 80)
print("BASELINE OPERATIONS")
print("-" * 80)
baseline = self.get_baseline_stats()
print(f"Total Operations: {baseline['total_operations']}")
print(f"Success Rate: {baseline['success_rate']:.1f}%")
latency = baseline["latency"]
print(
f"Latency: min={latency['min']:.4f}s, p50={latency['median']:.4f}s, "
f"p95={latency['p95']:.4f}s, max={latency['max']:.4f}s"
)
print("=" * 80 + "\n")
tests/load/oauth_pool.py
+485
View File
@@ -0,0 +1,485 @@
"""
OAuth User Pool Management for Load Testing.
Manages multiple OAuth-authenticated users for realistic multi-user load testing scenarios.
"""
import asyncio
import logging
from dataclasses import dataclass
from typing import Any
import httpx
from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client
logger = logging.getLogger(__name__)
@dataclass
class UserConfig:
"""Configuration for a single test user."""
username: str
password: str
display_name: str
email: str
groups: list[str]
@dataclass
class UserProfile:
"""Profile for an OAuth-authenticated user."""
username: str
password: str
token: str
session: ClientSession | None = None
streamable_context: Any | None = None # Store for proper cleanup
operation_count: int = 0
error_count: int = 0
class OAuthUserPool:
"""
Manages a pool of OAuth-authenticated users for load testing.
Handles token acquisition, session management, and user lifecycle.
"""
def __init__(
self,
admin_client: Any, # NextcloudClient with admin credentials
client_id: str,
client_secret: str,
callback_url: str,
token_endpoint: str,
authorization_endpoint: str,
):
self.admin_client = admin_client # For user management
self.nextcloud_host = str(admin_client._client.base_url)
self.client_id = client_id
self.client_secret = client_secret
self.callback_url = callback_url
self.token_endpoint = token_endpoint
self.authorization_endpoint = authorization_endpoint
self.users: dict[str, UserProfile] = {}
self._http_client: httpx.AsyncClient | None = None
async def __aenter__(self):
"""Initialize HTTP client."""
self._http_client = httpx.AsyncClient(verify=False, timeout=30.0)
return self
async def __aexit__(self, exc_type, exc_val, exc_tb):
"""Cleanup HTTP client."""
if self._http_client:
await self._http_client.aclose()
async def acquire_token(self, username: str, password: str, auth_code: str) -> str:
"""
Exchange authorization code for OAuth access token.
Args:
username: Username for logging
password: Password (for logging/debugging)
auth_code: Authorization code from OAuth flow
Returns:
OAuth access token
"""
logger.info(f"Exchanging auth code for access token (user: {username})...")
if not self._http_client:
raise RuntimeError(
"HTTP client not initialized - use async context manager"
)
# Exchange authorization code for access token
token_response = await self._http_client.post(
self.token_endpoint,
data={
"grant_type": "authorization_code",
"code": auth_code,
"redirect_uri": self.callback_url,
"client_id": self.client_id,
"client_secret": self.client_secret,
},
headers={"Content-Type": "application/x-www-form-urlencoded"},
)
token_response.raise_for_status()
token_data = token_response.json()
access_token = token_data.get("access_token")
if not access_token:
raise ValueError(f"No access token in response for {username}")
logger.info(f"Successfully acquired OAuth token for {username}")
return access_token
async def add_user(self, username: str, password: str, token: str) -> UserProfile:
"""
Add a user to the pool with their OAuth token.
Args:
username: Username
password: Password (for future re-auth if needed)
token: OAuth access token
Returns:
UserProfile for the added user
"""
if username in self.users:
logger.warning(f"User {username} already in pool, updating token")
profile = UserProfile(username=username, password=password, token=token)
self.users[username] = profile
logger.info(f"Added user {username} to pool (total: {len(self.users)})")
return profile
async def create_user_session(
self, username: str, mcp_url: str = "http://127.0.0.1:8001/mcp"
) -> ClientSession:
"""
Create an MCP client session for a user.
Args:
username: Username to create session for
mcp_url: MCP server URL
Returns:
Initialized ClientSession
Raises:
KeyError: If user not in pool
"""
if username not in self.users:
raise KeyError(f"User {username} not in pool")
profile = self.users[username]
# Create streamable HTTP connection with OAuth token in Authorization header
# This matches the pattern from tests/conftest.py create_mcp_client_session()
headers = {"Authorization": f"Bearer {profile.token}"}
streamable_context = streamablehttp_client(mcp_url, headers=headers)
try:
read_stream, write_stream, _ = await streamable_context.__aenter__()
session = ClientSession(read_stream, write_stream)
await session.__aenter__()
await session.initialize()
# Store both session and context for proper cleanup
profile.session = session
profile.streamable_context = streamable_context
logger.info(f"Created MCP session for {username}")
return session
except Exception as e:
# Clean up streamable context if session creation failed
try:
await streamable_context.__aexit__(None, None, None)
except Exception as cleanup_error:
logger.debug(f"Error during cleanup: {cleanup_error}")
raise e
async def close_user_session(self, username: str):
"""Close the MCP session for a user."""
if username not in self.users:
return
profile = self.users[username]
# Close ClientSession
if profile.session:
try:
await profile.session.__aexit__(None, None, None)
except Exception as e:
logger.debug(f"Error closing session for {username}: {e}")
profile.session = None
# Close streamable context
if profile.streamable_context:
try:
await profile.streamable_context.__aexit__(None, None, None)
except Exception as e:
logger.debug(f"Error closing streamable context for {username}: {e}")
profile.streamable_context = None
async def close_all_sessions(self):
"""Close all user sessions."""
for username in list(self.users.keys()):
await self.close_user_session(username)
def get_user(self, username: str) -> UserProfile:
"""Get user profile by username."""
if username not in self.users:
raise KeyError(f"User {username} not in pool")
return self.users[username]
def get_all_users(self) -> list[UserProfile]:
"""Get all user profiles."""
return list(self.users.values())
def record_operation(self, username: str, success: bool = True):
"""Record an operation for user stats."""
if username in self.users:
self.users[username].operation_count += 1
if not success:
self.users[username].error_count += 1
def get_stats(self) -> dict[str, dict[str, int | float]]:
"""Get per-user operation statistics."""
return {
username: {
"operations": profile.operation_count,
"errors": profile.error_count,
"success_rate": (
(profile.operation_count - profile.error_count)
/ max(profile.operation_count, 1)
* 100
),
}
for username, profile in self.users.items()
}
async def create_nextcloud_user(
self,
username: str,
password: str,
display_name: str | None = None,
email: str | None = None,
) -> UserConfig:
"""
Create a Nextcloud user via the Users API.
Args:
username: Username for the new user
password: Password for the new user
display_name: Optional display name
email: Optional email address
Returns:
UserConfig for the created user
Raises:
HTTPStatusError: If user creation fails
"""
logger.info(f"Creating Nextcloud user: {username}")
await self.admin_client.users.create_user(
userid=username,
password=password,
display_name=display_name or username,
email=email or f"{username}@benchmark.local",
)
logger.info(f"Successfully created Nextcloud user: {username}")
return UserConfig(
username=username,
password=password,
display_name=display_name or username,
email=email or f"{username}@benchmark.local",
groups=[],
)
async def delete_nextcloud_user(self, username: str):
"""
Delete a Nextcloud user via the Users API.
Args:
username: Username to delete
"""
logger.info(f"Deleting Nextcloud user: {username}")
try:
await self.admin_client.users.delete_user(userid=username)
logger.info(f"Successfully deleted Nextcloud user: {username}")
except Exception as e:
logger.warning(f"Failed to delete user {username}: {e}")
async def acquire_token_playwright(
self,
browser: Any,
username: str,
password: str,
state: str,
auth_states: dict[str, str],
) -> str:
"""
Acquire OAuth token via Playwright browser automation.
Based on conftest.py playwright_oauth_token fixture.
Automates the full OAuth flow:
1. Navigate to authorization URL
2. Fill login form
3. Handle OAuth consent
4. Wait for callback server to receive auth code
5. Exchange code for access token
Args:
browser: Playwright browser instance
username: Username to authenticate
password: Password for the user
state: Unique state parameter for this OAuth flow
auth_states: Dict mapping state -> auth_code (shared with callback server)
Returns:
OAuth access token
Raises:
TimeoutError: If callback not received within timeout
ValueError: If token exchange fails
"""
import time
from urllib.parse import quote
logger.info(f"Starting Playwright OAuth flow for {username}...")
logger.debug(f"Using state: {state[:16]}...")
# Construct authorization URL
auth_url = (
f"{self.authorization_endpoint}?"
f"response_type=code&"
f"client_id={self.client_id}&"
f"redirect_uri={quote(self.callback_url, safe='')}&"
f"state={state}&"
f"scope=openid%20profile%20email"
)
# Browser automation
context = await browser.new_context(ignore_https_errors=True)
page = await context.new_page()
try:
# Navigate to authorization URL
logger.debug("Navigating to authorization URL...")
await page.goto(auth_url, wait_until="networkidle", timeout=30000)
current_url = page.url
# Login if needed
if "/login" in current_url or "/index.php/login" in current_url:
logger.info(f"Logging in as {username}...")
await page.wait_for_selector('input[name="user"]', timeout=10000)
await page.fill('input[name="user"]', username)
await page.fill('input[name="password"]', password)
await page.click('button[type="submit"]')
await page.wait_for_load_state("networkidle", timeout=30000)
current_url = page.url
logger.info("Login completed")
# Handle OAuth consent if present
try:
authorize_button = await page.query_selector(
'button:has-text("Authorize"), button:has-text("Allow"), input[type="submit"][value*="uthoriz"]'
)
if authorize_button:
logger.info("Authorizing OAuth client...")
await authorize_button.click()
await page.wait_for_load_state("networkidle", timeout=10000)
except Exception as e:
logger.debug(f"No authorization needed: {e}")
# Wait for callback server to receive auth code
logger.info("Waiting for OAuth callback...")
timeout_seconds = 30
start_time = time.time()
while state not in auth_states:
if time.time() - start_time > timeout_seconds:
screenshot_path = f"/tmp/oauth_timeout_{username}.png"
await page.screenshot(path=screenshot_path)
logger.error(f"Screenshot saved to {screenshot_path}")
raise TimeoutError(
f"Timeout waiting for OAuth callback for {username}"
)
await asyncio.sleep(0.5)
auth_code = auth_states[state]
logger.info(f"Received auth code for {username}")
finally:
await context.close()
# Exchange code for token
logger.info(f"Exchanging auth code for access token ({username})...")
token_response = await self._http_client.post(
self.token_endpoint,
data={
"grant_type": "authorization_code",
"code": auth_code,
"redirect_uri": self.callback_url,
"client_id": self.client_id,
"client_secret": self.client_secret,
},
headers={"Content-Type": "application/x-www-form-urlencoded"},
)
token_response.raise_for_status()
token_data = token_response.json()
access_token = token_data.get("access_token")
if not access_token:
raise ValueError(f"No access token for {username}: {token_data}")
logger.info(f"Successfully acquired OAuth token for {username}")
return access_token
class UserSessionWrapper:
"""
Wrapper for a user-specific MCP session with operation tracking.
Provides a convenient interface for executing operations as a specific user.
"""
def __init__(self, username: str, session: ClientSession, pool: OAuthUserPool):
self.username = username
self.session = session
self.pool = pool
async def call_tool(self, tool_name: str, arguments: dict[str, Any]) -> Any:
"""
Call an MCP tool and record the operation.
Args:
tool_name: Name of the tool to call
arguments: Tool arguments
Returns:
Tool result
"""
try:
result = await self.session.call_tool(tool_name, arguments)
self.pool.record_operation(self.username, success=True)
return result
except Exception:
self.pool.record_operation(self.username, success=False)
raise
async def read_resource(self, uri: str) -> Any:
"""
Read an MCP resource and record the operation.
Args:
uri: Resource URI
Returns:
Resource data
"""
try:
result = await self.session.read_resource(uri)
self.pool.record_operation(self.username, success=True)
return result
except Exception:
self.pool.record_operation(self.username, success=False)
raise
def generate_secure_password(length: int = 20) -> str:
"""Generate a secure random password."""
import secrets
import string
alphabet = string.ascii_letters + string.digits + "!@#$%^&*()"
return "".join(secrets.choice(alphabet) for _ in range(length))
tests/load/oauth_workloads.py
+506
View File
@@ -0,0 +1,506 @@
"""
Multi-User Workflow Definitions for OAuth Load Testing.
Defines coordinated workflows that span multiple users, simulating realistic
collaborative scenarios like note sharing, file collaboration, and permission management.
"""
import asyncio
import json
import logging
import random
import time
import uuid
from abc import ABC, abstractmethod
from dataclasses import dataclass, field
from typing import Any, Awaitable, Callable
from tests.load.oauth_pool import UserSessionWrapper
logger = logging.getLogger(__name__)
@dataclass
class WorkflowStepResult:
"""Result of a single workflow step."""
step_name: str
user: str
success: bool
duration: float
error: str | None = None
data: dict[str, Any] = field(default_factory=dict)
@dataclass
class WorkflowResult:
"""Result of a complete workflow execution."""
workflow_name: str
success: bool
total_duration: float
steps: list[WorkflowStepResult]
participants: list[str]
error: str | None = None
@property
def steps_completed(self) -> int:
"""Count of successfully completed steps."""
return sum(1 for step in self.steps if step.success)
@property
def step_latencies(self) -> dict[str, float]:
"""Map of step names to their durations."""
return {step.step_name: step.duration for step in self.steps}
class Workflow(ABC):
"""
Base class for multi-user workflows.
A workflow represents a coordinated sequence of operations across multiple users,
such as creating and sharing a note, collaborative editing, or permission management.
"""
def __init__(self, name: str):
self.name = name
self.steps: list[WorkflowStepResult] = []
self.start_time: float | None = None
@abstractmethod
async def execute(self, users: list[UserSessionWrapper]) -> WorkflowResult:
"""
Execute the workflow with the given users.
Args:
users: List of UserSessionWrapper instances to use in the workflow
Returns:
WorkflowResult with execution details
"""
pass
async def _execute_step(
self,
step_name: str,
user: UserSessionWrapper,
operation: Callable[..., Awaitable[Any]],
**kwargs,
) -> WorkflowStepResult:
"""
Execute a single workflow step with timing and error handling.
Args:
step_name: Name of the step for reporting
user: User executing the step
operation: Async callable to execute
**kwargs: Arguments to pass to the operation
Returns:
WorkflowStepResult
"""
start = time.time()
try:
result = await operation(**kwargs)
duration = time.time() - start
step_result = WorkflowStepResult(
step_name=step_name,
user=user.username,
success=True,
duration=duration,
data={"result": result} if result else {},
)
self.steps.append(step_result)
return step_result
except Exception as e:
duration = time.time() - start
logger.error(f"Step {step_name} failed for user {user.username}: {e}")
step_result = WorkflowStepResult(
step_name=step_name,
user=user.username,
success=False,
duration=duration,
error=str(e),
)
self.steps.append(step_result)
return step_result
def _finish(self, success: bool, error: str | None = None) -> WorkflowResult:
"""
Finalize workflow and create result.
Args:
success: Whether the overall workflow succeeded
error: Optional error message
Returns:
WorkflowResult
"""
duration = time.time() - self.start_time if self.start_time else 0.0
participants = list(set(step.user for step in self.steps))
return WorkflowResult(
workflow_name=self.name,
success=success,
total_duration=duration,
steps=self.steps,
participants=participants,
error=error,
)
class NoteShareWorkflow(Workflow):
"""
Workflow: User A creates a note and shares it with User B, who then reads it.
Steps:
1. User A creates a note
2. User A shares the note with User B (read-only)
3. User B lists their shared notes (verify propagation)
4. User B reads the shared note
"""
def __init__(self):
super().__init__("note_share")
async def execute(self, users: list[UserSessionWrapper]) -> WorkflowResult:
"""Execute note sharing workflow."""
self.start_time = time.time()
if len(users) < 2:
return self._finish(False, error="Requires at least 2 users")
user_a, user_b = users[0], users[1]
unique_id = uuid.uuid4().hex[:8]
try:
# Step 1: User A creates note
create_result = await self._execute_step(
"create_note",
user_a,
lambda: user_a.call_tool(
"nc_notes_create_note",
{
"title": f"Shared Note {unique_id}",
"content": f"Content for workflow test {unique_id}",
"category": "Workflows",
},
),
)
if not create_result.success:
return self._finish(False, error="Failed to create note")
# Extract note ID
note_data = json.loads(create_result.data["result"].content[0].text)
note_id = note_data["id"]
# Step 2: User A shares note with User B
# Note: Sharing files/notes requires using WebDAV path
# Create a file first, then share it
share_result = await self._execute_step(
"share_note",
user_a,
lambda: user_a.call_tool(
"nc_share_create",
{
"path": f"/Notes/{note_data['category']}/{note_data['title']}.txt",
"share_with": user_b.username,
"share_type": 0, # User share
"permissions": 1, # Read-only
},
),
)
if not share_result.success:
logger.warning("Share creation failed, continuing anyway")
# Step 3: User B lists shares (measure propagation)
await self._execute_step(
"list_shared_with_me",
user_b,
lambda: user_b.call_tool("nc_share_list", {"shared_with_me": True}),
)
# Step 4: User B reads the note
await self._execute_step(
"read_shared_note",
user_b,
lambda: user_b.call_tool("nc_notes_get_note", {"note_id": note_id}),
)
# Cleanup: Delete the note
await user_a.call_tool("nc_notes_delete_note", {"note_id": note_id})
return self._finish(success=True)
except Exception as e:
logger.error(f"Note share workflow failed: {e}")
return self._finish(False, error=str(e))
class CollaborativeEditWorkflow(Workflow):
"""
Workflow: Multiple users edit the same note concurrently.
Steps:
1. User A creates a note
2. User A shares note with Users B, C (edit permissions)
3. All users read the note simultaneously
4. All users update the note simultaneously (test concurrent edits)
5. User A verifies final state
"""
def __init__(self):
super().__init__("collaborative_edit")
async def execute(self, users: list[UserSessionWrapper]) -> WorkflowResult:
"""Execute collaborative editing workflow."""
self.start_time = time.time()
if len(users) < 2:
return self._finish(False, error="Requires at least 2 users")
owner = users[0]
collaborators = users[1:]
unique_id = uuid.uuid4().hex[:8]
try:
# Step 1: Owner creates note
create_result = await self._execute_step(
"create_note",
owner,
lambda: owner.call_tool(
"nc_notes_create_note",
{
"title": f"Collab Note {unique_id}",
"content": f"Initial content {unique_id}",
"category": "Collaboration",
},
),
)
if not create_result.success:
return self._finish(False, error="Failed to create note")
note_data = json.loads(create_result.data["result"].content[0].text)
note_id = note_data["id"]
# Step 2: Read note concurrently by all users
read_tasks = []
for i, user in enumerate(users):
read_tasks.append(
self._execute_step(
f"concurrent_read_{i}",
user,
lambda uid=note_id: user.call_tool(
"nc_notes_get_note", {"note_id": uid}
),
)
)
await asyncio.gather(*read_tasks)
# Step 3: Append content concurrently by all collaborators
append_tasks = []
for i, user in enumerate(collaborators):
append_tasks.append(
self._execute_step(
f"concurrent_append_{i}",
user,
lambda _=i, u=user: u.call_tool(
"nc_notes_append_content",
{
"note_id": note_id,
"content": f"Addition from {u.username} at {time.time()}",
},
),
)
)
await asyncio.gather(*append_tasks)
# Step 4: Owner verifies final state
await self._execute_step(
"verify_final_state",
owner,
lambda: owner.call_tool("nc_notes_get_note", {"note_id": note_id}),
)
# Cleanup
await owner.call_tool("nc_notes_delete_note", {"note_id": note_id})
return self._finish(success=True)
except Exception as e:
logger.error(f"Collaborative edit workflow failed: {e}")
return self._finish(False, error=str(e))
class FileShareAndDownloadWorkflow(Workflow):
"""
Workflow: User A uploads a file, shares it with User B, who then downloads it.
Steps:
1. User A creates a file via WebDAV
2. User A shares the file with User B (read-only)
3. User B lists their shares
4. User B reads/downloads the file
"""
def __init__(self):
super().__init__("file_share_download")
async def execute(self, users: list[UserSessionWrapper]) -> WorkflowResult:
"""Execute file sharing workflow."""
self.start_time = time.time()
if len(users) < 2:
return self._finish(False, error="Requires at least 2 users")
user_a, user_b = users[0], users[1]
unique_id = uuid.uuid4().hex[:8]
file_path = f"/LoadTest_{unique_id}.txt"
try:
# Step 1: User A creates a file
content = f"Test file content {unique_id}\nCreated for workflow testing"
create_result = await self._execute_step(
"create_file",
user_a,
lambda: user_a.call_tool(
"nc_webdav_put_file",
{
"path": file_path,
"content": content,
"content_type": "text/plain",
},
),
)
if not create_result.success:
return self._finish(False, error="Failed to create file")
# Step 2: User A shares file with User B
share_result = await self._execute_step(
"share_file",
user_a,
lambda: user_a.call_tool(
"nc_share_create",
{
"path": file_path,
"share_with": user_b.username,
"share_type": 0,
"permissions": 1, # Read-only
},
),
)
if not share_result.success:
logger.warning("File share failed, continuing")
# Step 3: User B lists shared files
_ = await self._execute_step(
"list_shares",
user_b,
lambda: user_b.call_tool("nc_share_list", {"shared_with_me": True}),
)
# Step 4: User B downloads the file
_ = await self._execute_step(
"download_file",
user_b,
lambda: user_b.call_tool("nc_webdav_get_file", {"path": file_path}),
)
# Cleanup
await user_a.call_tool("nc_webdav_delete", {"path": file_path})
return self._finish(success=True)
except Exception as e:
logger.error(f"File share workflow failed: {e}")
return self._finish(False, error=str(e))
class MixedOAuthWorkload:
"""
Mixed workload combining baseline operations and coordinated workflows.
Distribution:
- 50% Baseline operations (individual user CRUD)
- 30% Note sharing workflows
- 15% Collaborative editing workflows
- 5% File sharing workflows
"""
def __init__(self, users: list[UserSessionWrapper]):
self.users = users
self.workflows = {
"note_share": NoteShareWorkflow(),
"collaborative_edit": CollaborativeEditWorkflow(),
"file_share": FileShareAndDownloadWorkflow(),
}
async def run_operation(self) -> WorkflowResult | dict[str, Any]:
"""
Execute one random operation (baseline or workflow).
Returns:
WorkflowResult for workflows, dict for baseline operations
"""
rand = random.random()
# 50% baseline operations (single-user)
if rand < 0.50:
return await self._run_baseline_operation()
# 30% note sharing
elif rand < 0.80:
users = random.sample(self.users, min(2, len(self.users)))
return await self.workflows["note_share"].execute(users)
# 15% collaborative editing
elif rand < 0.95:
users = random.sample(self.users, min(len(self.users), 3))
return await self.workflows["collaborative_edit"].execute(users)
# 5% file sharing
else:
users = random.sample(self.users, min(2, len(self.users)))
return await self.workflows["file_share"].execute(users)
async def _run_baseline_operation(self) -> dict[str, Any]:
"""Run a baseline single-user operation."""
user = random.choice(self.users)
operations = [
(
"search_notes",
lambda: user.call_tool("nc_notes_search_notes", {"query": ""}),
),
("list_files", lambda: user.call_tool("nc_webdav_list", {"path": "/"})),
("get_capabilities", lambda: user.read_resource("nc://capabilities")),
]
op_name, operation = random.choice(operations)
start = time.time()
try:
await operation()
duration = time.time() - start
return {
"type": "baseline",
"operation": op_name,
"user": user.username,
"success": True,
"duration": duration,
}
except Exception as e:
duration = time.time() - start
return {
"type": "baseline",
"operation": op_name,
"user": user.username,
"success": False,
"duration": duration,
"error": str(e),
}
tests/load/workloads.py
+282
View File
@@ -0,0 +1,282 @@
"""
Workload definitions for load testing the MCP server.
Defines realistic operation mixes and individual operation functions.
"""
import logging
import random
import time
import uuid
from mcp import ClientSession
logger = logging.getLogger(__name__)
class OperationResult:
"""Result of a single operation execution."""
def __init__(
self,
operation: str,
success: bool,
duration: float,
error: str | None = None,
):
self.operation = operation
self.success = success
self.duration = duration
self.error = error
self.timestamp = time.time()
class WorkloadOperations:
"""Collection of MCP operations for load testing."""
def __init__(self, session: ClientSession):
self.session = session
self._created_notes: list[int] = []
self._created_boards: list[int] = []
async def get_capabilities(self) -> OperationResult:
"""Fetch server capabilities (lightweight operation)."""
start = time.time()
try:
await self.session.read_resource("nc://capabilities")
duration = time.time() - start
return OperationResult("get_capabilities", True, duration)
except Exception as e:
duration = time.time() - start
return OperationResult("get_capabilities", False, duration, str(e))
async def list_notes(self) -> OperationResult:
"""List all notes (read operation)."""
start = time.time()
try:
await self.session.call_tool("nc_notes_search_notes", {"query": ""})
duration = time.time() - start
return OperationResult("list_notes", True, duration)
except Exception as e:
duration = time.time() - start
return OperationResult("list_notes", False, duration, str(e))
async def search_notes(self, query: str = "test") -> OperationResult:
"""Search notes by query (read operation with filtering)."""
start = time.time()
try:
await self.session.call_tool("nc_notes_search_notes", {"query": query})
duration = time.time() - start
return OperationResult("search_notes", True, duration)
except Exception as e:
duration = time.time() - start
return OperationResult("search_notes", False, duration, str(e))
async def create_note(self) -> OperationResult:
"""Create a new note (write operation)."""
start = time.time()
unique_id = uuid.uuid4().hex[:8]
try:
result = await self.session.call_tool(
"nc_notes_create_note",
{
"title": f"Load Test Note {unique_id}",
"content": f"Content for load test note {unique_id}",
"category": "LoadTesting",
},
)
duration = time.time() - start
# Track created note ID for cleanup
if result and len(result.content) > 0:
content = result.content[0]
if hasattr(content, "text"):
import json
note_data = json.loads(content.text)
note_id = note_data.get("id")
if note_id:
self._created_notes.append(note_id)
return OperationResult("create_note", True, duration)
except Exception as e:
duration = time.time() - start
return OperationResult("create_note", False, duration, str(e))
async def get_note(self, note_id: int) -> OperationResult:
"""Get a specific note by ID (read operation)."""
start = time.time()
try:
await self.session.call_tool("nc_notes_get_note", {"note_id": note_id})
duration = time.time() - start
return OperationResult("get_note", True, duration)
except Exception as e:
duration = time.time() - start
return OperationResult("get_note", False, duration, str(e))
async def update_note(self, note_id: int, etag: str) -> OperationResult:
"""Update an existing note (write operation)."""
start = time.time()
try:
await self.session.call_tool(
"nc_notes_update_note",
{
"note_id": note_id,
"etag": etag,
"title": f"Updated Note {note_id}",
"content": f"Updated content at {time.time()}",
"category": "LoadTesting",
},
)
duration = time.time() - start
return OperationResult("update_note", True, duration)
except Exception as e:
duration = time.time() - start
return OperationResult("update_note", False, duration, str(e))
async def delete_note(self, note_id: int) -> OperationResult:
"""Delete a note (write operation)."""
start = time.time()
try:
await self.session.call_tool("nc_notes_delete_note", {"note_id": note_id})
duration = time.time() - start
# Remove from tracking
if note_id in self._created_notes:
self._created_notes.remove(note_id)
return OperationResult("delete_note", True, duration)
except Exception as e:
duration = time.time() - start
return OperationResult("delete_note", False, duration, str(e))
async def list_webdav_files(self, path: str = "/") -> OperationResult:
"""List files via WebDAV (read operation)."""
start = time.time()
try:
await self.session.call_tool("nc_webdav_list", {"path": path})
duration = time.time() - start
return OperationResult("list_webdav_files", True, duration)
except Exception as e:
duration = time.time() - start
return OperationResult("list_webdav_files", False, duration, str(e))
async def list_calendars(self) -> OperationResult:
"""List calendars (read operation)."""
start = time.time()
try:
await self.session.call_tool("nc_calendar_list_calendars", {})
duration = time.time() - start
return OperationResult("list_calendars", True, duration)
except Exception as e:
duration = time.time() - start
return OperationResult("list_calendars", False, duration, str(e))
async def list_deck_boards(self) -> OperationResult:
"""List deck boards (read operation)."""
start = time.time()
try:
await self.session.call_tool("nc_deck_list_boards", {})
duration = time.time() - start
return OperationResult("list_deck_boards", True, duration)
except Exception as e:
duration = time.time() - start
return OperationResult("list_deck_boards", False, duration, str(e))
async def cleanup(self):
"""Clean up any resources created during testing."""
logger.info(f"Cleaning up {len(self._created_notes)} test notes...")
for note_id in self._created_notes[:]:
try:
await self.delete_note(note_id)
except Exception as e:
logger.warning(f"Failed to delete note {note_id}: {e}")
class MixedWorkload:
"""
Realistic mixed workload simulating typical MCP server usage.
Operation distribution:
- 40% Notes read (list/get/search)
- 20% Notes write (create/update/delete)
- 15% Notes search
- 10% WebDAV operations
- 10% Calendar operations
- 5% Other (capabilities, deck)
"""
def __init__(self, operations: WorkloadOperations):
self.ops = operations
# Pre-create some notes for read/update operations
self._warmup_note_ids: list[tuple[int, str]] = []
async def warmup(self, count: int = 10):
"""Create initial notes for read/update operations."""
logger.info(f"Warming up with {count} test notes...")
for _ in range(count):
result = await self.ops.create_note()
if result.success and self.ops._created_notes:
note_id = self.ops._created_notes[-1]
# Get the note to fetch its etag
try:
get_result = await self.ops.session.call_tool(
"nc_notes_get_note", {"note_id": note_id}
)
if get_result and len(get_result.content) > 0:
import json
note_data = json.loads(get_result.content[0].text)
etag = note_data.get("etag", "")
self._warmup_note_ids.append((note_id, etag))
except Exception as e:
logger.warning(f"Failed to get etag for note {note_id}: {e}")
async def run_operation(self) -> OperationResult:
"""Execute one random operation based on the workload distribution."""
rand = random.random()
# 40% reads (list/get/search)
if rand < 0.40:
op_rand = random.random()
if op_rand < 0.5:
return await self.ops.list_notes()
elif op_rand < 0.8 and self._warmup_note_ids:
note_id, _ = random.choice(self._warmup_note_ids)
return await self.ops.get_note(note_id)
else:
return await self.ops.search_notes()
# 20% writes (create/update/delete)
elif rand < 0.60:
op_rand = random.random()
if op_rand < 0.5:
return await self.ops.create_note()
elif op_rand < 0.8 and self._warmup_note_ids:
note_id, etag = random.choice(self._warmup_note_ids)
return await self.ops.update_note(note_id, etag)
elif self.ops._created_notes and len(self.ops._created_notes) > 5:
# Only delete if we have enough notes
note_id = random.choice(self.ops._created_notes)
return await self.ops.delete_note(note_id)
else:
return await self.ops.create_note()
# 15% search
elif rand < 0.75:
queries = ["test", "load", "note", "content", ""]
return await self.ops.search_notes(random.choice(queries))
# 10% WebDAV
elif rand < 0.85:
return await self.ops.list_webdav_files()
# 10% Calendar
elif rand < 0.95:
return await self.ops.list_calendars()
# 5% Other
else:
op_rand = random.random()
if op_rand < 0.5:
return await self.ops.get_capabilities()
else:
return await self.ops.list_deck_boards()
tests/server/test_calendar_todos_mcp.py
+476
View File
@@ -0,0 +1,476 @@
"""Integration tests for Calendar VTODO (task) MCP tools."""
import logging
from datetime import datetime, timedelta
import pytest
from mcp import ClientSession
from nextcloud_mcp_server.client import NextcloudClient
logger = logging.getLogger(__name__)
pytestmark = pytest.mark.integration
async def test_mcp_todo_complete_workflow(
nc_mcp_client: ClientSession, nc_client: NextcloudClient, temporary_calendar: str
):
"""Test complete todo workflow via MCP tools with verification via NextcloudClient."""
calendar_name = temporary_calendar
todo_uid = None
try:
# 1. Create todo via MCP
logger.info(f"Creating todo in {calendar_name} via MCP")
tomorrow = datetime.now() + timedelta(days=1)
create_result = await nc_mcp_client.call_tool(
"nc_calendar_create_todo",
{
"calendar_name": calendar_name,
"summary": "MCP Test Task",
"description": "Test task created via MCP tools",
"status": "NEEDS-ACTION",
"priority": 3,
"due": tomorrow.strftime("%Y-%m-%dT18:00:00"),
"categories": "testing,mcp",
},
)
assert create_result.isError is False
# Extract UID from the result
result_data = create_result.content[0].text
import json
result_json = json.loads(result_data)
todo_uid = result_json["uid"]
logger.info(f"Created todo with UID: {todo_uid}")
# 2. Verify todo creation via client
todos = await nc_client.calendar.list_todos(calendar_name)
assert any(t["uid"] == todo_uid for t in todos)
created_todo = next(t for t in todos if t["uid"] == todo_uid)
assert created_todo["summary"] == "MCP Test Task"
assert created_todo["status"] == "NEEDS-ACTION"
assert created_todo["priority"] == 3
# 3. List todos via MCP
logger.info(f"Listing todos in {calendar_name} via MCP")
list_result = await nc_mcp_client.call_tool(
"nc_calendar_list_todos",
{"calendar_name": calendar_name},
)
assert list_result.isError is False
list_data = json.loads(list_result.content[0].text)
assert "todos" in list_data
assert any(t["uid"] == todo_uid for t in list_data["todos"])
# 4. Update todo via MCP
logger.info(f"Updating todo {todo_uid} via MCP")
update_result = await nc_mcp_client.call_tool(
"nc_calendar_update_todo",
{
"calendar_name": calendar_name,
"todo_uid": todo_uid,
"summary": "MCP Test Task Updated",
"status": "IN-PROCESS",
"priority": 1,
"percent_complete": 50,
},
)
assert update_result.isError is False
# 5. Verify update via client
todos = await nc_client.calendar.list_todos(calendar_name)
updated_todo = next(t for t in todos if t["uid"] == todo_uid)
assert updated_todo["summary"] == "MCP Test Task Updated"
assert updated_todo["status"] == "IN-PROCESS"
assert updated_todo["priority"] == 1
assert updated_todo["percent_complete"] == 50
# 6. Delete todo via MCP
logger.info(f"Deleting todo {todo_uid} via MCP")
delete_result = await nc_mcp_client.call_tool(
"nc_calendar_delete_todo",
{"calendar_name": calendar_name, "todo_uid": todo_uid},
)
assert delete_result.isError is False
# 7. Verify deletion via client
todos = await nc_client.calendar.list_todos(calendar_name)
assert not any(t["uid"] == todo_uid for t in todos)
logger.info("Complete todo workflow test passed")
finally:
# Cleanup in case of failure
if todo_uid:
try:
await nc_client.calendar.delete_todo(calendar_name, todo_uid)
except Exception:
pass
async def test_mcp_list_todos_with_filters(
nc_mcp_client: ClientSession, nc_client: NextcloudClient, temporary_calendar: str
):
"""Test listing todos with various filters via MCP tools."""
calendar_name = temporary_calendar
created_uids = []
try:
# Create test todos with different properties
test_todos = [
{
"summary": "High Priority Task",
"status": "NEEDS-ACTION",
"priority": 1,
"categories": "urgent,work",
},
{
"summary": "In Progress Task",
"status": "IN-PROCESS",
"priority": 5,
"categories": "work",
},
{
"summary": "Low Priority Task",
"status": "NEEDS-ACTION",
"priority": 9,
"categories": "someday",
},
]
# Create todos via client
for todo_data in test_todos:
result = await nc_client.calendar.create_todo(calendar_name, todo_data)
created_uids.append(result["uid"])
# Test 1: Filter by status
logger.info("Testing filter by status")
result = await nc_mcp_client.call_tool(
"nc_calendar_list_todos",
{"calendar_name": calendar_name, "status": "NEEDS-ACTION"},
)
assert result.isError is False
import json
data = json.loads(result.content[0].text)
needs_action_todos = [t for t in data["todos"] if t["uid"] in created_uids]
assert len(needs_action_todos) == 2 # Two NEEDS-ACTION todos
# Test 2: Filter by priority
logger.info("Testing filter by minimum priority")
result = await nc_mcp_client.call_tool(
"nc_calendar_list_todos",
{"calendar_name": calendar_name, "min_priority": 1},
)
assert result.isError is False
data = json.loads(result.content[0].text)
high_priority_todos = [t for t in data["todos"] if t["uid"] in created_uids]
assert len(high_priority_todos) >= 1 # At least the priority 1 todo
# Test 3: Filter by categories
logger.info("Testing filter by categories")
result = await nc_mcp_client.call_tool(
"nc_calendar_list_todos",
{"calendar_name": calendar_name, "categories": "work"},
)
assert result.isError is False
data = json.loads(result.content[0].text)
work_todos = [t for t in data["todos"] if t["uid"] in created_uids]
assert len(work_todos) >= 2 # Two todos with "work" category
# Test 4: Filter by summary text
logger.info("Testing filter by summary text")
result = await nc_mcp_client.call_tool(
"nc_calendar_list_todos",
{"calendar_name": calendar_name, "summary_contains": "Priority"},
)
assert result.isError is False
data = json.loads(result.content[0].text)
priority_todos = [t for t in data["todos"] if t["uid"] in created_uids]
assert len(priority_todos) == 2 # Two have "Priority" in summary (High, Low)
logger.info("List todos with filters test passed")
finally:
# Cleanup
for uid in created_uids:
try:
await nc_client.calendar.delete_todo(calendar_name, uid)
except Exception:
pass
async def test_mcp_search_todos_across_calendars(
nc_mcp_client: ClientSession,
nc_client: NextcloudClient,
temporary_calendar: str,
shared_calendar_2: str,
):
"""Test searching todos across multiple calendars via MCP tools.
Note: Uses two shared test calendars to avoid rate limiting.
"""
cal1_name = temporary_calendar # First shared test calendar
cal2_name = shared_calendar_2 # Second shared test calendar
created_uids = []
try:
# Use existing shared calendars (no creation needed, avoiding rate limits)
# Create todos in both calendars
result1 = await nc_client.calendar.create_todo(
cal1_name,
{
"summary": "Task in Calendar 1",
"status": "NEEDS-ACTION",
"categories": "cal1",
},
)
created_uids.append((cal1_name, result1["uid"]))
result2 = await nc_client.calendar.create_todo(
cal2_name,
{
"summary": "Task in Calendar 2",
"status": "IN-PROCESS",
"categories": "cal2",
},
)
created_uids.append((cal2_name, result2["uid"]))
# Search across all calendars via MCP
logger.info("Searching todos across all calendars via MCP")
search_result = await nc_mcp_client.call_tool(
"nc_calendar_search_todos",
{},
)
assert search_result.isError is False
import json
data = json.loads(search_result.content[0].text)
assert "todos" in data
# Verify both todos are in the results
found_uids = {t["uid"] for t in data["todos"]}
assert result1["uid"] in found_uids
assert result2["uid"] in found_uids
# Verify calendar_name is included
our_todos = [
t for t in data["todos"] if t["uid"] in [result1["uid"], result2["uid"]]
]
for todo in our_todos:
assert "calendar_name" in todo
assert todo["calendar_name"] in [cal1_name, cal2_name]
# Test search with status filter
logger.info("Searching with status filter via MCP")
search_result = await nc_mcp_client.call_tool(
"nc_calendar_search_todos",
{"status": "IN-PROCESS"},
)
assert search_result.isError is False
data = json.loads(search_result.content[0].text)
in_process_todos = [
t for t in data["todos"] if t["uid"] in [uid for _, uid in created_uids]
]
assert len(in_process_todos) >= 1
logger.info("Search todos across calendars test passed")
finally:
# Cleanup: Only delete todos, not calendars (they're reused/built-in)
for cal_name, uid in created_uids:
try:
await nc_client.calendar.delete_todo(cal_name, uid)
except Exception:
pass
async def test_mcp_todo_status_transitions(
nc_mcp_client: ClientSession, nc_client: NextcloudClient, temporary_calendar: str
):
"""Test transitioning through different todo statuses via MCP tools."""
calendar_name = temporary_calendar
todo_uid = None
try:
# Create todo
result = await nc_client.calendar.create_todo(
calendar_name,
{"summary": "Status Transition Test", "status": "NEEDS-ACTION"},
)
todo_uid = result["uid"]
# Transition: NEEDS-ACTION → IN-PROCESS
logger.info("Transitioning todo to IN-PROCESS via MCP")
update_result = await nc_mcp_client.call_tool(
"nc_calendar_update_todo",
{
"calendar_name": calendar_name,
"todo_uid": todo_uid,
"status": "IN-PROCESS",
"percent_complete": 25,
},
)
assert update_result.isError is False
todos = await nc_client.calendar.list_todos(calendar_name)
todo = next(t for t in todos if t["uid"] == todo_uid)
assert todo["status"] == "IN-PROCESS"
assert todo["percent_complete"] == 25
# Transition: IN-PROCESS → COMPLETED
logger.info("Transitioning todo to COMPLETED via MCP")
completed_time = datetime.now().strftime("%Y-%m-%dT%H:%M:%S")
update_result = await nc_mcp_client.call_tool(
"nc_calendar_update_todo",
{
"calendar_name": calendar_name,
"todo_uid": todo_uid,
"status": "COMPLETED",
"percent_complete": 100,
"completed": completed_time,
},
)
assert update_result.isError is False
todos = await nc_client.calendar.list_todos(calendar_name)
todo = next(t for t in todos if t["uid"] == todo_uid)
assert todo["status"] == "COMPLETED"
assert todo["percent_complete"] == 100
assert "completed" in todo
logger.info("Todo status transitions test passed")
finally:
if todo_uid:
try:
await nc_client.calendar.delete_todo(calendar_name, todo_uid)
except Exception:
pass
async def test_mcp_todo_with_dates(
nc_mcp_client: ClientSession, nc_client: NextcloudClient, temporary_calendar: str
):
"""Test creating and managing todos with date fields via MCP tools."""
calendar_name = temporary_calendar
todo_uid = None
try:
now = datetime.now()
start_date = (now + timedelta(days=1)).strftime("%Y-%m-%dT09:00:00")
due_date = (now + timedelta(days=7)).strftime("%Y-%m-%dT17:00:00")
# Create todo with dates via MCP
logger.info("Creating todo with dates via MCP")
create_result = await nc_mcp_client.call_tool(
"nc_calendar_create_todo",
{
"calendar_name": calendar_name,
"summary": "Task with Dates",
"description": "Test task with various date fields",
"status": "NEEDS-ACTION",
"dtstart": start_date,
"due": due_date,
},
)
assert create_result.isError is False
import json
result_data = json.loads(create_result.content[0].text)
todo_uid = result_data["uid"]
# Verify dates via client
todos = await nc_client.calendar.list_todos(calendar_name)
created_todo = next(t for t in todos if t["uid"] == todo_uid)
assert created_todo["summary"] == "Task with Dates"
assert "dtstart" in created_todo
assert "due" in created_todo
logger.info("Todo with dates test passed")
finally:
if todo_uid:
try:
await nc_client.calendar.delete_todo(calendar_name, todo_uid)
except Exception:
pass
async def test_mcp_todo_categories(
nc_mcp_client: ClientSession, nc_client: NextcloudClient, temporary_calendar: str
):
"""Test creating and managing todos with categories via MCP tools."""
calendar_name = temporary_calendar
todo_uid = None
try:
# Create todo with multiple categories via MCP
logger.info("Creating todo with categories via MCP")
create_result = await nc_mcp_client.call_tool(
"nc_calendar_create_todo",
{
"calendar_name": calendar_name,
"summary": "Task with Categories",
"status": "NEEDS-ACTION",
"categories": "work,meeting,important,quarterly",
},
)
assert create_result.isError is False
import json
result_data = json.loads(create_result.content[0].text)
todo_uid = result_data["uid"]
# Verify categories via client
todos = await nc_client.calendar.list_todos(calendar_name)
created_todo = next(t for t in todos if t["uid"] == todo_uid)
assert "categories" in created_todo
categories_str = created_todo["categories"]
assert "work" in categories_str
assert "meeting" in categories_str
assert "important" in categories_str
assert "quarterly" in categories_str
# Update categories via MCP
logger.info("Updating todo categories via MCP")
update_result = await nc_mcp_client.call_tool(
"nc_calendar_update_todo",
{
"calendar_name": calendar_name,
"todo_uid": todo_uid,
"categories": "updated,new-category",
},
)
assert update_result.isError is False
# Verify updated categories
todos = await nc_client.calendar.list_todos(calendar_name)
updated_todo = next(t for t in todos if t["uid"] == todo_uid)
categories_str = updated_todo["categories"]
assert "updated" in categories_str
assert "new-category" in categories_str
logger.info("Todo categories test passed")
finally:
if todo_uid:
try:
await nc_client.calendar.delete_todo(calendar_name, todo_uid)
except Exception:
pass
tests/integration/test_contacts_mcp.py → tests/server/test_contacts_mcp.py
View File
tests/server/test_cookbook_mcp.py
+554
View File
@@ -0,0 +1,554 @@
import asyncio
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
async def test_mcp_cookbook_create_and_read_recipe(
nc_mcp_client: ClientSession, nc_client: NextcloudClient
):
"""Test creating and reading a recipe via MCP tools with verification via NextcloudClient."""
unique_suffix = uuid.uuid4().hex[:8]
recipe_name = f"MCP Test Recipe {unique_suffix}"
recipe_data = {
"name": recipe_name,
"description": "A test recipe created via MCP tools",
"recipeIngredient": ["100g flour", "2 eggs", "200ml milk"],
"recipeInstructions": ["Mix ingredients", "Cook for 20 minutes", "Serve hot"],
"recipeCategory": "MCPTesting",
"keywords": f"mcp,testing,{unique_suffix}",
"recipeYield": 4,
"prepTime": "PT15M",
"cookTime": "PT20M",
"totalTime": "PT35M",
}
created_recipe_id = None
try:
# 1. Create recipe via MCP
logger.info(f"Creating recipe via MCP: {recipe_name}")
create_result = await nc_mcp_client.call_tool(
"nc_cookbook_create_recipe",
{
"name": recipe_name,
"description": recipe_data["description"],
"ingredients": recipe_data["recipeIngredient"],
"instructions": recipe_data["recipeInstructions"],
"category": recipe_data["recipeCategory"],
"keywords": recipe_data["keywords"],
"recipe_yield": recipe_data["recipeYield"],
"prep_time": recipe_data["prepTime"],
"cook_time": recipe_data["cookTime"],
"total_time": recipe_data["totalTime"],
},
)
assert create_result.isError is False, (
f"MCP recipe creation failed: {create_result.content}"
)
create_response = json.loads(create_result.content[0].text)
created_recipe_id = create_response["id"]
logger.info(f"Recipe created via MCP with ID: {created_recipe_id}")
# 2. Verify creation via direct NextcloudClient
direct_recipe = await nc_client.cookbook.get_recipe(created_recipe_id)
assert direct_recipe["name"] == recipe_name
assert direct_recipe["description"] == "A test recipe created via MCP tools"
assert len(direct_recipe["recipeIngredient"]) == 3
assert len(direct_recipe["recipeInstructions"]) == 3
assert direct_recipe["recipeCategory"] == "MCPTesting"
# 3. Read recipe via MCP
logger.info(f"Reading recipe via MCP: {created_recipe_id}")
read_result = await nc_mcp_client.call_tool(
"nc_cookbook_get_recipe", {"recipe_id": created_recipe_id}
)
assert read_result.isError is False, (
f"MCP recipe read failed: {read_result.content}"
)
read_recipe = json.loads(read_result.content[0].text)
assert read_recipe["name"] == recipe_name
assert read_recipe["description"] == "A test recipe created via MCP tools"
assert len(read_recipe["recipeIngredient"]) == 3
logger.info(f"Successfully verified recipe {created_recipe_id} via MCP")
finally:
# Cleanup
if created_recipe_id is not None:
try:
await nc_client.cookbook.delete_recipe(created_recipe_id)
logger.info(f"Cleaned up recipe {created_recipe_id}")
except Exception as e:
logger.warning(f"Failed to cleanup recipe: {e}")
async def test_mcp_cookbook_update_recipe(
nc_mcp_client: ClientSession, nc_client: NextcloudClient
):
"""Test updating a recipe via MCP tools."""
unique_suffix = uuid.uuid4().hex[:8]
recipe_name = f"MCP Update Test {unique_suffix}"
recipe_data = {
"name": recipe_name,
"description": "Original description",
"recipeIngredient": ["100g flour"],
"recipeInstructions": ["Mix ingredients"],
"recipeCategory": "Original",
}
created_recipe_id = None
try:
# 1. Create recipe via direct client
logger.info(f"Creating recipe for update test: {recipe_name}")
created_recipe_id = await nc_client.cookbook.create_recipe(recipe_data)
# 2. Update recipe via MCP (tool handles fetching current recipe internally)
logger.info(f"Updating recipe via MCP: {created_recipe_id}")
update_result = await nc_mcp_client.call_tool(
"nc_cookbook_update_recipe",
{
"recipe_id": created_recipe_id,
"description": "Updated via MCP",
"ingredients": ["100g flour", "2 eggs"],
"instructions": ["Mix ingredients", "Cook"],
"category": "Updated",
},
)
assert update_result.isError is False, (
f"MCP recipe update failed: {update_result.content}"
)
# 4. Verify update via direct NextcloudClient
await asyncio.sleep(1) # Allow propagation
updated_recipe = await nc_client.cookbook.get_recipe(created_recipe_id)
assert updated_recipe["description"] == "Updated via MCP"
assert len(updated_recipe["recipeIngredient"]) == 2
assert len(updated_recipe["recipeInstructions"]) == 2
assert updated_recipe["recipeCategory"] == "Updated"
logger.info(f"Successfully updated recipe {created_recipe_id} via MCP")
finally:
# Cleanup
if created_recipe_id is not None:
try:
await nc_client.cookbook.delete_recipe(created_recipe_id)
logger.info(f"Cleaned up recipe {created_recipe_id}")
except Exception as e:
logger.warning(f"Failed to cleanup recipe: {e}")
async def test_mcp_cookbook_delete_recipe(
nc_mcp_client: ClientSession, nc_client: NextcloudClient
):
"""Test deleting a recipe via MCP tools."""
unique_suffix = uuid.uuid4().hex[:8]
recipe_name = f"MCP Delete Test {unique_suffix}"
recipe_data = {
"name": recipe_name,
"description": "Recipe to be deleted",
"recipeIngredient": ["test"],
"recipeInstructions": ["test"],
}
created_recipe_id = None
try:
# 1. Create recipe via direct client
logger.info(f"Creating recipe for delete test: {recipe_name}")
created_recipe_id = await nc_client.cookbook.create_recipe(recipe_data)
# 2. Delete recipe via MCP
logger.info(f"Deleting recipe via MCP: {created_recipe_id}")
delete_result = await nc_mcp_client.call_tool(
"nc_cookbook_delete_recipe", {"recipe_id": created_recipe_id}
)
assert delete_result.isError is False, (
f"MCP recipe deletion failed: {delete_result.content}"
)
# 3. Verify deletion via direct NextcloudClient
try:
await nc_client.cookbook.get_recipe(created_recipe_id)
pytest.fail("Recipe should have been deleted but was still found")
except Exception:
# Expected - recipe should be deleted
logger.info(f"Successfully verified recipe {created_recipe_id} was deleted")
created_recipe_id = None # Mark as cleaned up
finally:
# Cleanup in case of test failure
if created_recipe_id is not None:
try:
await nc_client.cookbook.delete_recipe(created_recipe_id)
logger.info(f"Cleaned up recipe {created_recipe_id}")
except Exception as e:
logger.warning(f"Failed to cleanup recipe: {e}")
async def test_mcp_cookbook_import_recipe_from_url(
nc_mcp_client: ClientSession,
nc_client: NextcloudClient,
):
"""Test importing a recipe from a URL via MCP tools.
This is the key feature test - importing recipes from URLs using schema.org metadata.
Uses an nginx container to serve reliable, controlled test data.
"""
# Use the nginx container hostname within the Docker network
test_url = "http://recipes/black-pepper-tofu"
created_recipe_id = None
try:
# 1. Import recipe via MCP
logger.info(f"Importing recipe from nginx container via MCP: {test_url}")
import_result = await nc_mcp_client.call_tool(
"nc_cookbook_import_recipe", {"url": test_url}
)
assert import_result.isError is False, (
f"MCP recipe import failed: {import_result.content}"
)
import_response = json.loads(import_result.content[0].text)
created_recipe_id = int(import_response["recipe_id"])
imported_recipe = import_response["recipe"]
logger.info(f"Successfully imported recipe via MCP: {imported_recipe['name']}")
# 2. Verify basic recipe structure
assert imported_recipe["name"] == "Black Pepper Tofu"
assert imported_recipe.get("description")
assert len(imported_recipe.get("recipeIngredient", [])) > 0
assert len(imported_recipe.get("recipeInstructions", [])) > 0
assert imported_recipe.get("recipeCategory") == "Main Course"
assert "tofu" in imported_recipe.get("keywords", "").lower()
# 3. Verify we can read it back via direct NextcloudClient
retrieved = await nc_client.cookbook.get_recipe(created_recipe_id)
assert retrieved["name"] == imported_recipe["name"]
logger.info(f"Verified imported recipe ID: {created_recipe_id}")
finally:
# Cleanup
if created_recipe_id is not None:
try:
await nc_client.cookbook.delete_recipe(created_recipe_id)
logger.info(f"Cleaned up imported recipe {created_recipe_id}")
except Exception as e:
logger.warning(f"Failed to cleanup imported recipe: {e}")
async def test_mcp_cookbook_search_recipes(
nc_mcp_client: ClientSession, nc_client: NextcloudClient
):
"""Test searching recipes via MCP tools."""
unique_keyword = f"mcptestkeyword{uuid.uuid4().hex[:8]}"
recipe_name = f"MCP Search Test {uuid.uuid4().hex[:8]}"
recipe_data = {
"name": recipe_name,
"description": f"Recipe for testing MCP search with {unique_keyword}",
"keywords": unique_keyword,
"recipeIngredient": ["test ingredient"],
"recipeInstructions": ["test instruction"],
}
created_recipe_id = None
try:
# 1. Create recipe via direct client
logger.info(f"Creating recipe for search test with keyword: {unique_keyword}")
created_recipe_id = await nc_client.cookbook.create_recipe(recipe_data)
# 2. Allow time for indexing
await asyncio.sleep(2)
# 3. Search for the recipe via MCP
logger.info(f"Searching for recipes via MCP with keyword: {unique_keyword}")
search_result = await nc_mcp_client.call_tool(
"nc_cookbook_search_recipes", {"query": unique_keyword}
)
assert search_result.isError is False, (
f"MCP recipe search failed: {search_result.content}"
)
search_response = json.loads(search_result.content[0].text)
search_results = search_response["recipes"]
assert isinstance(search_results, list)
assert len(search_results) > 0
# 4. Verify our recipe is in the results
found = any(str(r.get("id")) == str(created_recipe_id) for r in search_results)
assert found, f"Recipe {created_recipe_id} not found in search results"
logger.info(
f"Successfully found recipe {created_recipe_id} in MCP search results"
)
finally:
# Cleanup
if created_recipe_id is not None:
try:
await nc_client.cookbook.delete_recipe(created_recipe_id)
logger.info(f"Cleaned up recipe {created_recipe_id}")
except Exception as e:
logger.warning(f"Failed to cleanup recipe: {e}")
async def test_mcp_cookbook_list_recipes(
nc_mcp_client: ClientSession, nc_client: NextcloudClient
):
"""Test listing all recipes via MCP tools."""
logger.info("Listing all recipes via MCP")
list_result = await nc_mcp_client.call_tool("nc_cookbook_list_recipes", {})
assert list_result.isError is False, (
f"MCP list recipes failed: {list_result.content}"
)
list_response = json.loads(list_result.content[0].text)
recipes = list_response["recipes"]
assert isinstance(recipes, list)
logger.info(f"Found {len(recipes)} recipes via MCP")
async def test_mcp_cookbook_categories_workflow(
nc_mcp_client: ClientSession, nc_client: NextcloudClient
):
"""Test category listing and filtering via MCP tools."""
unique_category = f"MCPTestCategory{uuid.uuid4().hex[:8]}"
recipe_name = f"MCP Category Test {uuid.uuid4().hex[:8]}"
recipe_data = {
"name": recipe_name,
"recipeCategory": unique_category,
"recipeIngredient": ["test"],
"recipeInstructions": ["test"],
}
created_recipe_id = None
try:
# 1. Create recipe in test category
logger.info(f"Creating recipe in category: {unique_category}")
created_recipe_id = await nc_client.cookbook.create_recipe(recipe_data)
# 2. Allow time for indexing
await asyncio.sleep(2)
# 3. List categories via MCP
logger.info("Listing categories via MCP")
categories_result = await nc_mcp_client.call_tool(
"nc_cookbook_list_categories", {}
)
assert categories_result.isError is False, (
f"MCP list categories failed: {categories_result.content}"
)
categories_response = json.loads(categories_result.content[0].text)
categories = categories_response["categories"]
assert isinstance(categories, list)
logger.info(f"Found {len(categories)} categories via MCP")
# 4. Get recipes in this category via MCP
logger.info(f"Getting recipes in category via MCP: {unique_category}")
category_recipes_result = await nc_mcp_client.call_tool(
"nc_cookbook_get_recipes_in_category", {"category": unique_category}
)
assert category_recipes_result.isError is False, (
f"MCP get recipes in category failed: {category_recipes_result.content}"
)
category_recipes_response = json.loads(category_recipes_result.content[0].text)
recipes_in_category = category_recipes_response["recipes"]
assert isinstance(recipes_in_category, list)
assert len(recipes_in_category) > 0
# 5. Verify our recipe is in the results
found = any(
str(r.get("id")) == str(created_recipe_id) for r in recipes_in_category
)
assert found, (
f"Recipe {created_recipe_id} not found in category {unique_category}"
)
logger.info(f"Successfully found recipe in category {unique_category} via MCP")
finally:
# Cleanup
if created_recipe_id is not None:
try:
await nc_client.cookbook.delete_recipe(created_recipe_id)
logger.info(f"Cleaned up recipe {created_recipe_id}")
except Exception as e:
logger.warning(f"Failed to cleanup recipe: {e}")
async def test_mcp_cookbook_keywords_workflow(
nc_mcp_client: ClientSession, nc_client: NextcloudClient
):
"""Test keyword listing and filtering via MCP tools."""
unique_keyword = f"mcptesttag{uuid.uuid4().hex[:8]}"
recipe_name = f"MCP Keyword Test {uuid.uuid4().hex[:8]}"
recipe_data = {
"name": recipe_name,
"keywords": f"{unique_keyword},mcptesting",
"recipeIngredient": ["test"],
"recipeInstructions": ["test"],
}
created_recipe_id = None
try:
# 1. Create recipe with test keywords
logger.info(f"Creating recipe with keyword: {unique_keyword}")
created_recipe_id = await nc_client.cookbook.create_recipe(recipe_data)
# 2. Allow extra time for indexing and trigger reindex
await asyncio.sleep(3)
await nc_client.cookbook.reindex()
await asyncio.sleep(2)
# 3. List keywords via MCP
logger.info("Listing keywords via MCP")
keywords_result = await nc_mcp_client.call_tool("nc_cookbook_list_keywords", {})
assert keywords_result.isError is False, (
f"MCP list keywords failed: {keywords_result.content}"
)
keywords_response = json.loads(keywords_result.content[0].text)
keywords = keywords_response["keywords"]
assert isinstance(keywords, list)
logger.info(f"Found {len(keywords)} keywords via MCP")
# 4. Get recipes with this keyword via MCP
logger.info(f"Getting recipes with keyword via MCP: {unique_keyword}")
keyword_recipes_result = await nc_mcp_client.call_tool(
"nc_cookbook_get_recipes_with_keywords", {"keywords": [unique_keyword]}
)
assert keyword_recipes_result.isError is False, (
f"MCP get recipes with keywords failed: {keyword_recipes_result.content}"
)
keyword_recipes_response = json.loads(keyword_recipes_result.content[0].text)
recipes_with_keywords = keyword_recipes_response["recipes"]
assert isinstance(recipes_with_keywords, list)
# Keyword filtering might not find recipes immediately due to indexing
if len(recipes_with_keywords) > 0:
# Verify our recipe is in the results if any are found
found = any(
str(r.get("id")) == str(created_recipe_id)
for r in recipes_with_keywords
)
if found:
logger.info(
f"Successfully found recipe with keyword {unique_keyword} via MCP"
)
else:
logger.warning(
f"Recipe {created_recipe_id} not in keyword results via MCP, but other recipes found"
)
else:
logger.warning(
f"No recipes found with keyword {unique_keyword} via MCP - may be indexing delay"
)
finally:
# Cleanup
if created_recipe_id is not None:
try:
await nc_client.cookbook.delete_recipe(created_recipe_id)
logger.info(f"Cleaned up recipe {created_recipe_id}")
except Exception as e:
logger.warning(f"Failed to cleanup recipe: {e}")
async def test_mcp_cookbook_config_and_version(
nc_mcp_client: ClientSession, nc_client: NextcloudClient
):
"""Test getting Cookbook configuration and version via MCP resources."""
# 1. Get version via MCP resource
logger.info("Getting Cookbook version via MCP resource")
version_result = await nc_mcp_client.read_resource("cookbook://version")
assert len(version_result.contents) > 0
version_response = json.loads(version_result.contents[0].text)
assert "cookbook_version" in version_response
assert "api_version" in version_response
logger.info(f"Cookbook version from MCP: {version_response}")
# 2. Verify version via direct NextcloudClient
direct_version = await nc_client.cookbook.get_version()
assert direct_version["cookbook_version"] == version_response["cookbook_version"]
assert (
direct_version["api_version"]["epoch"]
== version_response["api_version"]["epoch"]
)
# 3. Get config via MCP resource
logger.info("Getting Cookbook config via MCP resource")
config_result = await nc_mcp_client.read_resource("cookbook://config")
assert len(config_result.contents) > 0
config_response = json.loads(config_result.contents[0].text)
assert isinstance(config_response, dict)
logger.info(f"Cookbook config from MCP: {config_response}")
# 4. Verify config via direct NextcloudClient
direct_config = await nc_client.cookbook.get_config()
# Both should be dicts - exact match may vary based on config
assert isinstance(config_response, dict)
assert isinstance(direct_config, dict)
logger.info("Successfully verified Cookbook version and config via MCP")
async def test_mcp_cookbook_reindex(
nc_mcp_client: ClientSession, nc_client: NextcloudClient
):
"""Test triggering a recipe reindex via MCP tools."""
logger.info("Triggering recipe reindex via MCP")
reindex_result = await nc_mcp_client.call_tool("nc_cookbook_reindex", {})
assert reindex_result.isError is False, (
f"MCP reindex failed: {reindex_result.content}"
)
reindex_response = json.loads(reindex_result.content[0].text)
assert isinstance(reindex_response["message"], str)
logger.info(f"Reindex result from MCP: {reindex_response['message']}")
tests/server/test_deck_advanced_features.py
+569
View File
@@ -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")

Some files were not shown because too many files have changed in this diff Show More