From d153e965208b73b1c66083c6609bf7d380296cf9 Mon Sep 17 00:00:00 2001 From: Chris Coutinho Date: Thu, 30 Apr 2026 01:27:53 +0200 Subject: [PATCH] docs: address Login Flow v2 review feedback MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Fix issues raised by reviewer on PR #743: - troubleshooting.md: renumber "Getting Help" steps (4→3, 5→4) after earlier consolidation left a gap - installation.md: drop stale "OIDC app" prerequisite; admin access is now optional under Login Flow v2 (works on stock Nextcloud 16+) - semantic-search-architecture.md: rename VECTOR_SYNC_ENABLED to ENABLE_SEMANTIC_SEARCH in the Status callout (renamed in v0.58.0) - configuration.md: remove Quick Start references to deprecated oauth-multi-user / oauth-advanced templates and point to login-flow-v2.md; update "OAuth, Multi-User BasicAuth" label to "Login Flow v2, Multi-User BasicAuth" - auth-flows.md: fix background-sync diagram so Encrypt+persist step no longer crosses into the Nextcloud column Co-Authored-By: Claude Opus 4.7 (1M context) --- docs/auth-flows.md | 4 ++-- docs/configuration.md | 11 ++++++----- docs/installation.md | 2 +- docs/semantic-search-architecture.md | 2 +- docs/troubleshooting.md | 4 ++-- 5 files changed, 12 insertions(+), 11 deletions(-) diff --git a/docs/auth-flows.md b/docs/auth-flows.md index 54cff468..28eaeef0 100644 --- a/docs/auth-flows.md +++ b/docs/auth-flows.md @@ -94,8 +94,8 @@ Astrolabe MCP Server Nextcloud │ │ │ │── Store app password ──────▶│ │ │ (via management API) │ │ - │ │── Encrypt + persist ──────▶│ - │ │ (SQLite, Fernet) │ + │ │ [Encrypt + persist locally]│ + │ │ (SQLite, Fernet) │ │◀── Confirmation ────────────│ │ │ │ │ │ [Background job] │ │ diff --git a/docs/configuration.md b/docs/configuration.md index 254839a1..f57bfa2c 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -11,15 +11,16 @@ We provide mode-specific configuration templates for quick setup: ```bash # Choose a template based on your deployment mode: cp env.sample.single-user .env # Simplest - one user, local dev -cp env.sample.oauth-multi-user .env # Recommended - multi-user OAuth -cp env.sample.oauth-advanced .env # Advanced - token exchange mode +cp env.sample .env # Full reference with all options -# Or start from the full example: -cp env.sample .env +# For multi-user Login Flow v2 (recommended), see the dedicated guide: +# docs/login-flow-v2.md#setup # Edit .env with your Nextcloud details ``` +> **Note:** The legacy templates `env.sample.oauth-multi-user` and `env.sample.oauth-advanced` configure the deprecated direct-OAuth-to-Nextcloud modes. New deployments should use [Login Flow v2](login-flow-v2.md) for multi-user setups. + Then choose your deployment mode: - [Single-User BasicAuth](#single-user-basicauth-mode) - Simplest for personal instances @@ -210,7 +211,7 @@ QDRANT_URL=http://qdrant:6333 OLLAMA_BASE_URL=http://ollama:11434 ``` -> **Note:** In multi-user modes (OAuth, Multi-User BasicAuth), enabling `ENABLE_SEMANTIC_SEARCH` automatically enables background operations and refresh token storage. You don't need to set `ENABLE_BACKGROUND_OPERATIONS` separately! +> **Note:** In multi-user modes (Login Flow v2, Multi-User BasicAuth), enabling `ENABLE_SEMANTIC_SEARCH` automatically enables background operations and refresh token storage. You don't need to set `ENABLE_BACKGROUND_OPERATIONS` separately! ### Qdrant Vector Database Modes diff --git a/docs/installation.md b/docs/installation.md index e3a8b3f8..0f99af62 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -6,7 +6,7 @@ This guide covers installing the Nextcloud MCP server on your system. - **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 +- **Administrator access** *(optional)* - Only needed to customise app-password policies in Nextcloud settings; not required for any deployment mode (single-user, multi-user BasicAuth, or Login Flow v2) ## Installation Methods diff --git a/docs/semantic-search-architecture.md b/docs/semantic-search-architecture.md index 1dd3613e..87776bd5 100644 --- a/docs/semantic-search-architecture.md +++ b/docs/semantic-search-architecture.md @@ -4,7 +4,7 @@ This document explains the architecture of the semantic search feature in the Ne > [!IMPORTANT] > **Status: Experimental** -> - Disabled by default (`VECTOR_SYNC_ENABLED=false`) +> - Disabled by default (`ENABLE_SEMANTIC_SEARCH=false`) > - Currently supports **Notes, Files (PDFs), News items, and Deck cards** > - Requires additional infrastructure (Qdrant vector database + Ollama embedding service) > - RAG answer generation requires MCP client sampling support diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index fdc42399..39a18a6e 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -423,7 +423,7 @@ curl -u "$NEXTCLOUD_USERNAME:$NEXTCLOUD_PASSWORD" \ For Login Flow v2 mode, see [Login Flow v2 troubleshooting](login-flow-v2.md#troubleshooting). -### 4. Check Versions +### 3. Check Versions ```bash # MCP Server version @@ -435,7 +435,7 @@ python3 --version # Nextcloud version (check in admin panel) ``` -### 5. Open an Issue +### 4. Open an Issue If problems persist, open an issue on the [GitHub repository](https://github.com/cbcoutinho/nextcloud-mcp-server/issues) with: