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
co-authored by
Claude Sonnet 4.5
Claude Sonnet 4.5
parent
34273ec01e
commit
1a5bb10cd0
@@ -4,6 +4,146 @@ 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.
|
||||
|
||||
> **Upgrading from v0.57.x?** See the [Configuration Migration Guide](configuration-migration-v2.md) for help with new variable names.
|
||||
|
||||
## Configuration Issues (v0.58.0+)
|
||||
|
||||
### Issue: Deprecation warning for VECTOR_SYNC_ENABLED
|
||||
|
||||
**Symptom:**
|
||||
```
|
||||
WARNING: VECTOR_SYNC_ENABLED is deprecated. Please use ENABLE_SEMANTIC_SEARCH instead.
|
||||
```
|
||||
|
||||
**Cause:** You're using the old variable name from v0.57.x.
|
||||
|
||||
**Solution:**
|
||||
```bash
|
||||
# In your .env file, replace:
|
||||
VECTOR_SYNC_ENABLED=true
|
||||
|
||||
# With:
|
||||
ENABLE_SEMANTIC_SEARCH=true
|
||||
```
|
||||
|
||||
See [Configuration Migration Guide](configuration-migration-v2.md) for complete migration instructions.
|
||||
|
||||
---
|
||||
|
||||
### Issue: Deprecation warning for ENABLE_OFFLINE_ACCESS
|
||||
|
||||
**Symptom:**
|
||||
```
|
||||
WARNING: ENABLE_OFFLINE_ACCESS is deprecated. Please use ENABLE_BACKGROUND_OPERATIONS instead.
|
||||
```
|
||||
|
||||
**Cause:** You're using the old variable name from v0.57.x.
|
||||
|
||||
**Solution:**
|
||||
|
||||
**If you have semantic search enabled:**
|
||||
```bash
|
||||
# In multi-user modes, you can remove ENABLE_OFFLINE_ACCESS entirely!
|
||||
# ENABLE_SEMANTIC_SEARCH automatically enables background operations
|
||||
|
||||
# Before (v0.57.x):
|
||||
ENABLE_OFFLINE_ACCESS=true
|
||||
VECTOR_SYNC_ENABLED=true
|
||||
|
||||
# After (v0.58.0+):
|
||||
ENABLE_SEMANTIC_SEARCH=true # This is all you need!
|
||||
```
|
||||
|
||||
**If you only want background operations (no semantic search):**
|
||||
```bash
|
||||
# Replace:
|
||||
ENABLE_OFFLINE_ACCESS=true
|
||||
|
||||
# With:
|
||||
ENABLE_BACKGROUND_OPERATIONS=true
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Issue: "Invalid MCP_DEPLOYMENT_MODE"
|
||||
|
||||
**Symptom:**
|
||||
```
|
||||
ValueError: Invalid MCP_DEPLOYMENT_MODE: 'oauth'. Valid values: single_user_basic, multi_user_basic, oauth_single_audience, oauth_token_exchange, smithery
|
||||
```
|
||||
|
||||
**Cause:** Invalid value for `MCP_DEPLOYMENT_MODE`.
|
||||
|
||||
**Solution:**
|
||||
Use one of the valid mode values:
|
||||
```bash
|
||||
# Correct values:
|
||||
MCP_DEPLOYMENT_MODE=single_user_basic # Single-user with username/password
|
||||
MCP_DEPLOYMENT_MODE=multi_user_basic # Multi-user BasicAuth
|
||||
MCP_DEPLOYMENT_MODE=oauth_single_audience # OAuth (recommended)
|
||||
MCP_DEPLOYMENT_MODE=oauth_token_exchange # OAuth with token exchange
|
||||
MCP_DEPLOYMENT_MODE=smithery # Smithery deployment
|
||||
```
|
||||
|
||||
Or remove `MCP_DEPLOYMENT_MODE` to use automatic detection.
|
||||
|
||||
---
|
||||
|
||||
### Issue: Missing TOKEN_ENCRYPTION_KEY when semantic search enabled
|
||||
|
||||
**Symptom:**
|
||||
```
|
||||
Error: [oauth_single_audience] TOKEN_ENCRYPTION_KEY is required when ENABLE_SEMANTIC_SEARCH is enabled
|
||||
```
|
||||
|
||||
**Cause:** In multi-user modes, semantic search automatically enables background operations, which require encrypted token storage.
|
||||
|
||||
**Solution:**
|
||||
Generate an encryption key and add required token storage configuration:
|
||||
|
||||
```bash
|
||||
# Generate encryption key
|
||||
python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
|
||||
|
||||
# Add to .env:
|
||||
TOKEN_ENCRYPTION_KEY=<generated-key>
|
||||
TOKEN_STORAGE_DB=/app/data/tokens.db
|
||||
NEXTCLOUD_OIDC_CLIENT_ID=your-client-id # Required for app password retrieval
|
||||
NEXTCLOUD_OIDC_CLIENT_SECRET=your-client-secret
|
||||
```
|
||||
|
||||
**Why this happens:**
|
||||
- v0.58.0+ automatically enables background operations when `ENABLE_SEMANTIC_SEARCH=true` in multi-user modes
|
||||
- Background operations need encrypted refresh token storage
|
||||
- This simplifies configuration but requires the encryption infrastructure
|
||||
|
||||
See [Configuration Guide - Semantic Search](configuration.md#semantic-search-configuration-optional) for details.
|
||||
|
||||
---
|
||||
|
||||
### Issue: Both old and new variable names set
|
||||
|
||||
**Symptom:**
|
||||
```
|
||||
WARNING: Both ENABLE_SEMANTIC_SEARCH and VECTOR_SYNC_ENABLED are set. Using ENABLE_SEMANTIC_SEARCH.
|
||||
```
|
||||
|
||||
**Cause:** You have both the old and new variable names in your configuration.
|
||||
|
||||
**Solution:**
|
||||
Remove the old variable name:
|
||||
```bash
|
||||
# Remove this line:
|
||||
VECTOR_SYNC_ENABLED=true
|
||||
|
||||
# Keep this line:
|
||||
ENABLE_SEMANTIC_SEARCH=true
|
||||
```
|
||||
|
||||
The server will use the new name and ignore the old one, but it's cleaner to remove the old variable entirely.
|
||||
|
||||
---
|
||||
|
||||
## OAuth Issues (Quick Reference)
|
||||
|
||||
### Issue: "OAuth mode requires NEXTCLOUD_HOST environment variable"
|
||||
|
||||
Reference in New Issue
Block a user