feat(config): consolidate configuration with smart dependency resolution (ADR-021)
Simplifies configuration by consolidating overlapping settings and adding automatic dependency resolution. This makes semantic search configuration significantly easier for users while maintaining 100% backward compatibility. ## Key Changes ### Variable Renaming (Backward Compatible) - `VECTOR_SYNC_ENABLED` → `ENABLE_SEMANTIC_SEARCH` (old name still works) - `ENABLE_OFFLINE_ACCESS` → `ENABLE_BACKGROUND_OPERATIONS` (old name still works) - Deprecation warnings logged when old names used - Old names will be removed in v1.0.0 ### Smart Dependency Resolution - `ENABLE_SEMANTIC_SEARCH` automatically enables background operations in multi-user modes - No need to set both `ENABLE_OFFLINE_ACCESS` and `VECTOR_SYNC_ENABLED` anymore - Single-user mode doesn't auto-enable background ops (not needed) ### Explicit Mode Selection (Optional) - New `MCP_DEPLOYMENT_MODE` environment variable - Valid values: single_user_basic, multi_user_basic, oauth_single_audience, oauth_token_exchange, smithery - Removes ambiguity about which deployment mode is active - Falls back to auto-detection if not set (existing behavior) ### Configuration Templates - Reorganized `env.sample` by deployment mode with clear sections - Added mode-specific quick-start templates: - `env.sample.single-user` - Simplest configuration - `env.sample.oauth-multi-user` - Recommended multi-user - `env.sample.oauth-advanced` - Token exchange mode ## Implementation Details ### Files Modified - `nextcloud_mcp_server/config.py` - Smart dependency resolution helpers - `nextcloud_mcp_server/config_validators.py` - Simplified validation, explicit mode - `tests/unit/test_config_validators.py` - 19 new tests (60 total, all passing) - `env.sample` - Reorganized by deployment mode - `docs/configuration.md` - Complete rewrite with consolidated approach - `docs/troubleshooting.md` - New consolidation troubleshooting section - `README.md` - Updated variable references ### New Files - `docs/ADR-021-configuration-consolidation.md` - Architecture decision record - `docs/configuration-migration-v2.md` - Comprehensive migration guide - `env.sample.single-user` - Single-user quick-start template - `env.sample.oauth-multi-user` - OAuth multi-user quick-start template - `env.sample.oauth-advanced` - Token exchange quick-start template ## User Impact ### Before (Confusing) ```bash ENABLE_OFFLINE_ACCESS=true # Why both? VECTOR_SYNC_ENABLED=true # What's the relationship? ``` ### After (Simplified) ```bash MCP_DEPLOYMENT_MODE=oauth_single_audience # Explicit (optional) ENABLE_SEMANTIC_SEARCH=true # Auto-enables background ops! ``` ### Benefits - 📉 2 fewer variables to understand for semantic search - 📋 Clear intent ("I want semantic search") - 🎯 Explicit mode declaration available - 🔄 100% backward compatible - ✅ All 265 unit tests passing ## Testing - All 60 config validation tests passing - 10 new tests for configuration consolidation - 9 new tests for explicit mode selection - Full unit test suite: 265 tests passing - Backward compatibility verified ## Migration Users can migrate at their own pace. Old variable names continue working with deprecation warnings. See docs/configuration-migration-v2.md for detailed migration instructions. Related: ADR-021 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
Chris Coutinho
@@ -0,0 +1,77 @@
|
||||
# ============================================
|
||||
# OAUTH MULTI-USER QUICK START (Recommended)
|
||||
# ============================================
|
||||
# Multi-user deployment with OAuth authentication
|
||||
# Use for: Multi-user production deployments, enhanced security
|
||||
# Features: Single-audience tokens, automatic client registration (DCR)
|
||||
#
|
||||
# Copy this file to .env and configure
|
||||
|
||||
# ===== REQUIRED SETTINGS =====
|
||||
# Your Nextcloud instance URL (without trailing slash)
|
||||
NEXTCLOUD_HOST=https://nextcloud.example.com
|
||||
|
||||
# ===== REQUIRED: LEAVE USERNAME/PASSWORD EMPTY =====
|
||||
# OAuth mode activates when these are NOT set
|
||||
NEXTCLOUD_USERNAME=
|
||||
NEXTCLOUD_PASSWORD=
|
||||
|
||||
# ===== OPTIONAL: EXPLICIT MODE DECLARATION =====
|
||||
# Recommended for clarity
|
||||
MCP_DEPLOYMENT_MODE=oauth_single_audience
|
||||
|
||||
# ===== OPTIONAL: PRE-REGISTERED OAUTH CLIENT =====
|
||||
# If you pre-register the OAuth client instead of using DCR:
|
||||
#NEXTCLOUD_OIDC_CLIENT_ID=your-client-id
|
||||
#NEXTCLOUD_OIDC_CLIENT_SECRET=your-client-secret
|
||||
|
||||
# MCP Server URL (for OAuth redirects)
|
||||
NEXTCLOUD_MCP_SERVER_URL=http://localhost:8000
|
||||
|
||||
# ===== OPTIONAL: SEMANTIC SEARCH (Recommended) =====
|
||||
# AI-powered semantic search with automatic background operation setup
|
||||
#
|
||||
# When you enable semantic search in multi-user mode:
|
||||
# 1. ENABLE_SEMANTIC_SEARCH automatically enables background operations
|
||||
# 2. Server requests refresh tokens for offline indexing
|
||||
# 3. Tokens are stored encrypted in TOKEN_STORAGE_DB
|
||||
# 4. No need to set ENABLE_BACKGROUND_OPERATIONS separately!
|
||||
#
|
||||
ENABLE_SEMANTIC_SEARCH=true
|
||||
|
||||
# Vector Database (required for semantic search)
|
||||
QDRANT_URL=http://qdrant:6333
|
||||
# OR for in-memory mode:
|
||||
#QDRANT_LOCATION=:memory:
|
||||
|
||||
# Embedding Provider (required for semantic search)
|
||||
# Option 1: Ollama (recommended for local deployment)
|
||||
OLLAMA_BASE_URL=http://ollama:11434
|
||||
OLLAMA_EMBEDDING_MODEL=nomic-embed-text
|
||||
|
||||
# Option 2: Amazon Bedrock (for AWS deployments)
|
||||
#AWS_REGION=us-east-1
|
||||
#BEDROCK_EMBEDDING_MODEL=amazon.titan-embed-text-v2:0
|
||||
|
||||
# Token Storage (required for background operations - auto-enabled by semantic search)
|
||||
# Generate encryption key: python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
|
||||
TOKEN_ENCRYPTION_KEY=your-encryption-key-here
|
||||
TOKEN_STORAGE_DB=/app/data/tokens.db
|
||||
|
||||
# ===== OPTIONAL: DOCUMENT PROCESSING =====
|
||||
# Extract text from PDFs, images, DOCX for semantic search
|
||||
#ENABLE_DOCUMENT_PROCESSING=true
|
||||
#ENABLE_UNSTRUCTURED=true
|
||||
#UNSTRUCTURED_API_URL=http://unstructured:8000
|
||||
|
||||
# ===== SUMMARY OF AUTO-ENABLEMENT =====
|
||||
# With ENABLE_SEMANTIC_SEARCH=true in OAuth mode:
|
||||
# ✅ Background operations enabled automatically
|
||||
# ✅ Refresh token storage enabled automatically
|
||||
# ✅ OAuth credentials required (DCR or pre-registered)
|
||||
# ✅ Encryption key required for token storage
|
||||
#
|
||||
# You only need to set ENABLE_SEMANTIC_SEARCH and provide the required
|
||||
# infrastructure (Qdrant, Ollama, encryption key). The rest is automatic!
|
||||
|
||||
# For more advanced configuration, see env.sample
|
||||
Reference in New Issue
Block a user