Update ADRs to reflect that vector database and semantic search support
multiple Nextcloud apps (notes, calendar, deck, files, contacts) rather
than being notes-specific. Introduce semantic:read/write OAuth scopes
to replace app-specific scope requirements for cross-app search.
Changes:
- ADR-007: Add plugin architecture (DocumentScanner, DocumentProcessor,
DocumentVerifier) for multi-app vector sync
- ADR-008: Rename tools from nc_notes_semantic_* to nc_semantic_*, update
scope from notes:read to semantic:read
- ADR-009: NEW - Document decision to use generic semantic:read scope
with dual-phase authorization instead of requiring all app scopes
- oauth-architecture.md: Add semantic:read/write scope documentation
- README.md: Move semantic search to dedicated section separate from Notes
This is a breaking change that correctly positions semantic search as a
cross-app capability before broader adoption. Existing deployments will
need to re-authenticate with the new semantic:read scope.
Relates to user request to decouple vector database from notes-only model
and establish proper OAuth scope boundaries for multi-app semantic search.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Add nc_notes_semantic_search_answer tool that combines semantic search
with MCP sampling to generate natural language answers from retrieved
Nextcloud Notes. This enables Retrieval-Augmented Generation (RAG)
patterns without requiring a server-side LLM.
Key features:
- Client-side LLM generation via ctx.session.create_message()
- Graceful fallback when sampling unavailable
- Proper source citations in generated answers
- No results optimization (skips sampling when no docs found)
- Comprehensive unit and integration tests
Implementation details:
- SamplingSearchResponse model with generated_answer and sources
- Fixed prompt template with document context and citation instructions
- Model preferences hint Claude Sonnet for balanced performance
- Falls back to returning documents without answer on sampling failure
Updates:
- Add ADR-008 documenting sampling architecture decision
- Add MCP sampling pattern guidance to CLAUDE.md
- Update README.md and docs/notes.md (7 → 9 tools)
- Add 4 unit tests and 6 integration tests
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Import recipes from URLs using schema.org metadata
- Full CRUD operations for recipes
- Search, categorize, and organize recipes
- Manage keywords/tags and categories
- Configure app settings and trigger reindexing
BREAKING CHANGE: FASTMCP_-prefixed env vars have been replaced by CLI
arguments. Refer to the README for updated usage.
Usage: python -m nextcloud_mcp_server.app [OPTIONS]
Options:
-h, --host TEXT
-p, --port INTEGER
-w, --workers INTEGER
-r, --reload
--log-level [critical|error|warning|info|debug|trace]
-t, --transport [sse|streamable-http]
-e, --enable-app [notes|tables|webdav|calendar|contacts]
Enable specific Nextcloud app APIs. Can be
specified multiple times. If not specified,
all apps are enabled.
--help Show this message and exit.
- Add nc_webdav_list_directory tool for browsing any NextCloud directory
- Add nc_webdav_read_file tool with automatic text/binary content handling
- Add nc_webdav_write_file tool supporting text and base64 binary content
- Add nc_webdav_create_directory tool for creating directories
- Add nc_webdav_delete_resource tool for deleting files and directories
- Extend WebDAV client beyond Notes attachments to general file operations
- Add XML parsing for WebDAV PROPFIND responses with metadata extraction
- Improve type annotations throughout codebase for better IDE support
- Add comprehensive documentation with usage examples
This transforms the NextCloud MCP server from a limited Notes/Tables tool
into a full-featured file system interface, enabling complete NextCloud
file management through LLM interactions.
Chris Coutinho