From 394b27ee4a172bf0fd16571120fa98074ea7113c Mon Sep 17 00:00:00 2001 From: Chris Coutinho Date: Fri, 17 Oct 2025 03:21:54 +0200 Subject: [PATCH] docs: Update README with experimental warnings of OIDC support --- README.md | 61 +++++++++++++++++++++++++++++++++++++------------------ 1 file changed, 41 insertions(+), 20 deletions(-) diff --git a/README.md b/README.md index d311391..0359dfa 100644 --- a/README.md +++ b/README.md @@ -6,6 +6,9 @@ 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. +> [!WARNING] +> **OAuth Support is Experimental**: OAuth/OIDC authentication requires manual patches to upstream Nextcloud apps and is not production-ready. For most users, **Basic Auth is recommended**. See [OAuth Upstream Status](docs/oauth-upstream-status.md) for details on required patches. + > [!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 endpoint for external LLMs. 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. See our [detailed comparison](docs/comparison-context-agent.md) to understand which approach fits your use case. @@ -30,8 +33,16 @@ Want to see another Nextcloud app supported? [Open an issue](https://github.com/ | Mode | Security | Best For | |------|----------|----------| -| **OAuth2/OIDC** ✅ | 🔒 High | Production, multi-user deployments | -| **Basic Auth** ⚠️ | Lower | Development, testing | +| **OAuth2/OIDC** ⚠️ **Experimental** | 🔒 High | Testing, evaluation (requires patches) | +| **Basic Auth** ✅ | Lower | Development, testing, production | + +> [!IMPORTANT] +> **OAuth is experimental** and requires manual patches to upstream Nextcloud apps. Specifically: +> - **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 +> - **Production use**: Wait for upstream patches to be merged into official releases +> +> See [OAuth Upstream Status](docs/oauth-upstream-status.md) for detailed information on required patches and workarounds. OAuth2/OIDC provides secure, per-user authentication with access tokens. See [Authentication Guide](docs/authentication.md) for details. @@ -62,29 +73,35 @@ Create a `.env` file: cp env.sample .env ``` -**For OAuth (recommended):** -```dotenv -NEXTCLOUD_HOST=https://your.nextcloud.instance.com -``` - -**For Basic Auth:** +**For Basic Auth (recommended for most users):** ```dotenv NEXTCLOUD_HOST=https://your.nextcloud.instance.com NEXTCLOUD_USERNAME=your_username NEXTCLOUD_PASSWORD=your_app_password ``` +**For OAuth (experimental - requires patches):** +```dotenv +NEXTCLOUD_HOST=https://your.nextcloud.instance.com +``` + See [Configuration Guide](docs/configuration.md) for all options. ### 3. Set Up Authentication -**OAuth Setup (recommended):** -1. Install Nextcloud OIDC apps (`oidc` + `user_oidc`) -2. Enable dynamic client registration -3. Configure Bearer token validation -4. Start the server +**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 -See [OAuth Quick Start](docs/quickstart-oauth.md) for 5-minute setup or [OAuth Setup Guide](docs/oauth-setup.md) for production deployment. +**OAuth Setup (experimental):** +1. Install Nextcloud OIDC apps (`oidc` + `user_oidc`) +2. **Apply required patches** to `user_oidc` app (see [OAuth Upstream Status](docs/oauth-upstream-status.md)) +3. Enable dynamic client registration +4. Configure Bearer token validation +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 @@ -92,12 +109,15 @@ See [OAuth Quick Start](docs/quickstart-oauth.md) for 5-minute setup or [OAuth S # Load environment variables export $(grep -v '^#' .env | xargs) -# Start the server +# Start with Basic Auth (default) +uv run nextcloud-mcp-server + +# Or start with OAuth (experimental - requires patches) uv run nextcloud-mcp-server --oauth # Or with Docker docker run -p 127.0.0.1:8000:8000 --env-file .env --rm \ - ghcr.io/cbcoutinho/nextcloud-mcp-server:latest --oauth + ghcr.io/cbcoutinho/nextcloud-mcp-server:latest ``` The server starts on `http://127.0.0.1:8000` by default. @@ -127,12 +147,12 @@ Or connect from: ### Architecture - **[Comparison with Context Agent](docs/comparison-context-agent.md)** - How this MCP server differs from Nextcloud's Context Agent -### OAuth Documentation +### OAuth Documentation (Experimental) - **[OAuth Quick Start](docs/quickstart-oauth.md)** - 5-minute setup guide -- **[OAuth Setup Guide](docs/oauth-setup.md)** - Production deployment +- **[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 +- **[Upstream Status](docs/oauth-upstream-status.md)** - **Required patches and PRs** ⚠️ ### Reference - **[Troubleshooting](docs/troubleshooting.md)** - Common issues and solutions @@ -230,7 +250,8 @@ Contributions are welcome! [![MseeP.ai Security Assessment](https://mseep.net/pr/cbcoutinho-nextcloud-mcp-server-badge.png)](https://mseep.ai/app/cbcoutinho-nextcloud-mcp-server) This project takes security seriously: -- OAuth2/OIDC support for secure authentication +- 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