Merge pull request #137 from cbcoutinho/feature/claude-code

Feature/claude code

Author: cbcoutinho

.pre-commit-config.yaml

@@ -6,8 +6,15 @@ repos:
   - id: commitizen-branch
     stages:
     - pre-push
-- repo: https://github.com/astral-sh/ruff-pre-commit
-  rev: v0.12.5
+- repo: local
   hooks:
     - id: ruff-check
+      name: ruff-check
+      entry: uv run ruff check
+      language: system
+      types: [python]
     - id: ruff-format
+      name: ruff-format
+      entry: uv run ruff format
+      language: system
+      types: [python]

CLAUDE.md

@@ -0,0 +1,118 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Development Commands
+
+### Testing
+```bash
+# Run all tests
+uv run pytest
+
+# Run integration tests only
+uv run pytest -m integration
+
+# Run tests with coverage
+uv run pytest --cov
+
+# Skip integration tests
+uv run pytest -m "not integration"
+```
+
+### Code Quality
+```bash
+# Format and lint code
+uv run ruff check
+uv run ruff format
+
+# Type checking
+# No explicit type checker configured - this is a Python project using ruff for linting
+```
+
+### Running the Server
+```bash
+# Local development - load environment variables and run
+export $(grep -v '^#' .env | xargs)
+mcp run --transport sse nextcloud_mcp_server.app:mcp
+
+# Docker development environment with Nextcloud instance
+docker-compose up
+
+# After code changes, rebuild and restart only the MCP server container
+docker-compose up --build -d mcp
+
+# Build Docker image
+docker build -t nextcloud-mcp-server .
+```
+
+### Environment Setup
+```bash
+# Install dependencies
+uv sync
+
+# Install development dependencies
+uv sync --group dev
+```
+
+## Architecture Overview
+
+This is a Python MCP (Model Context Protocol) server that provides LLM integration with Nextcloud. The architecture follows a layered pattern:
+
+### Core Components
+
+- **`nextcloud_mcp_server/app.py`** - Main MCP server entry point using FastMCP framework
+- **`nextcloud_mcp_server/client/`** - HTTP client implementations for different Nextcloud APIs
+- **`nextcloud_mcp_server/server/`** - MCP tool/resource definitions that expose client functionality
+- **`nextcloud_mcp_server/controllers/`** - Business logic controllers (e.g., notes search)
+
+### Client Architecture
+
+- **`NextcloudClient`** - Main orchestrating client that manages all app-specific clients
+- **`BaseNextcloudClient`** - Abstract base class providing common HTTP functionality and retry logic
+- **App-specific clients**: `NotesClient`, `CalendarClient`, `ContactsClient`, `TablesClient`, `WebDAVClient`
+
+### Server Integration
+
+Each Nextcloud app has a corresponding server module that:
+1. Defines MCP tools using `@mcp.tool()` decorators
+2. Defines MCP resources using `@mcp.resource()` decorators
+3. Uses the context pattern to access the `NextcloudClient` instance
+
+### Supported Nextcloud Apps
+
+- **Notes** - Full CRUD operations and search
+- **Calendar** - CalDAV integration with events, recurring events, attendees
+- **Contacts** - CardDAV integration with address book operations
+- **Tables** - Row-level operations on Nextcloud Tables
+- **WebDAV** - Complete file system access
+
+### Key Patterns
+
+1. **Environment-based configuration** - Uses `NextcloudClient.from_env()` to load credentials from environment variables
+2. **Async/await throughout** - All operations are async using httpx
+3. **Retry logic** - `@retry_on_429` decorator handles rate limiting
+4. **Context injection** - MCP context provides access to the authenticated client instance
+5. **Modular design** - Each Nextcloud app is isolated in its own client/server pair
+
+### Testing Structure
+
+- **Integration tests** in `tests/integration/` - Test real Nextcloud API interactions
+- **Fixtures** in `tests/conftest.py` - Shared test setup and utilities
+- Tests are marked with `@pytest.mark.integration` for selective running
+- **Important**: Integration tests run against live Docker containers. After making code changes to the MCP server, rebuild only the MCP container with `docker-compose up --build -d mcp` before running tests
+
+#### Testing Best Practices
+- **Always restart MCP server** after code changes with `docker-compose up --build -d mcp`
+- **Use existing fixtures** from `tests/conftest.py` to avoid duplicate setup work:
+  - `nc_mcp_client` - MCP client session for tool/resource testing  
+  - `nc_client` - Direct NextcloudClient for setup/cleanup operations
+  - `temporary_note` - Creates and cleans up test notes automatically
+  - `temporary_addressbook` - Creates and cleans up test address books
+  - `temporary_contact` - Creates and cleans up test contacts
+- **Avoid creating standalone test scripts** - use pytest with proper fixtures instead
+
+### Configuration Files
+
+- **`pyproject.toml`** - Python project configuration using uv for dependency management
+- **`.env`** (from `env.sample`) - Environment variables for Nextcloud connection
+- **`docker-compose.yml`** - Complete development environment with Nextcloud + database

nextcloud_mcp_server/client/base.py

@@ -39,6 +39,13 @@ async def wrapper(*args, **kwargs):
                         f"429 Client Error: Too Many Requests, Number of attempts: {retries}"
                     )
                     time.sleep(5)
+                elif e.response.status_code == 404:
+                    # 404 errors are often expected (e.g., checking if attachments exist)
+                    # Log as debug instead of warning
+                    logger.debug(
+                        f"HTTPStatusError {e.response.status_code}: {e}, Number of attempts: {retries}"
+                    )
+                    raise
                 else:
                     logger.warning(
                         f"HTTPStatusError {e.response.status_code}: {e}, Number of attempts: {retries}"

nextcloud_mcp_server/client/calendar.py

@@ -238,27 +238,33 @@ async def update_event(
         event_data: Dict[str, Any],
         etag: str = "",
     ) -> Dict[str, Any]:
-        """Update an existing calendar event."""
+        """Update an existing calendar event while preserving all existing properties."""
         event_filename = f"{event_uid}.ics"
         event_path = f"{self._get_caldav_base_path()}/{calendar_name}/{event_filename}"
 
-        # Get existing event data to merge with updates
-        existing_event_data = {}
+        # Get raw iCal content to preserve all properties including extended ones
+        raw_ical_content = ""
         if not etag:
             try:
-                existing_event_data, current_etag = await self.get_event(
+                raw_ical_content, current_etag = await self._get_raw_ical(
                     calendar_name, event_uid
                 )
                 etag = current_etag
             except Exception:
-                # Continue without etag if we can't get it
-                pass
-
-        # Merge existing data with new data (new data takes precedence)
-        merged_data = {**existing_event_data, **event_data}
+                # Fall back to creating new iCal if we can't get existing
+                logger.warning(
+                    f"Could not fetch existing iCal for {event_uid}, creating new"
+                )
+                raw_ical_content = ""
 
-        # Create updated iCalendar event
-        ical_content = self._create_ical_event(merged_data, event_uid)
+        # Create updated iCalendar event preserving existing properties
+        if raw_ical_content:
+            ical_content = self._merge_ical_properties(
+                raw_ical_content, event_data, event_uid
+            )
+        else:
+            # Fallback to creating new iCal if we couldn't get existing
+            ical_content = self._create_ical_event(event_data, event_uid)
 
         headers = {
             "Content-Type": "text/calendar; charset=utf-8",
@@ -949,3 +955,122 @@ async def delete_calendar(self, calendar_name: str) -> Dict[str, Any]:
         except Exception as e:
             logger.error(f"Error deleting calendar {calendar_name}: {e}")
             raise
+
+    async def _get_raw_ical(
+        self, calendar_name: str, event_uid: str
+    ) -> Tuple[str, str]:
+        """Get raw iCal content for an event without parsing."""
+        event_filename = f"{event_uid}.ics"
+        event_path = f"{self._get_caldav_base_path()}/{calendar_name}/{event_filename}"
+
+        headers = {"Accept": "text/calendar"}
+
+        try:
+            response = await self._make_request("GET", event_path, headers=headers)
+            etag = response.headers.get("etag", "")
+            return response.text, etag
+        except Exception as e:
+            logger.error(f"Error getting raw iCal for {event_uid}: {e}")
+            raise
+
+    def _merge_ical_properties(
+        self, raw_ical: str, event_data: Dict[str, Any], event_uid: str
+    ) -> str:
+        """Merge new event data into existing raw iCal while preserving all properties."""
+        try:
+            # Parse existing iCal
+            cal = Calendar.from_ical(raw_ical)
+
+            # Find the VEVENT component
+            for component in cal.walk():
+                if component.name == "VEVENT":
+                    # Update only the properties that were provided in event_data
+                    if "title" in event_data:
+                        component["SUMMARY"] = event_data["title"]
+                    if "description" in event_data:
+                        component["DESCRIPTION"] = event_data["description"]
+                    if "location" in event_data:
+                        component["LOCATION"] = event_data["location"]
+                    if "status" in event_data:
+                        component["STATUS"] = event_data["status"].upper()
+                    if "priority" in event_data:
+                        component["PRIORITY"] = event_data["priority"]
+                    if "privacy" in event_data:
+                        component["CLASS"] = event_data["privacy"].upper()
+                    if "url" in event_data:
+                        component["URL"] = event_data["url"]
+
+                    # Handle dates
+                    if "start_datetime" in event_data:
+                        start_str = event_data["start_datetime"]
+                        all_day = event_data.get("all_day", False)
+                        if all_day:
+                            start_date = dt.datetime.fromisoformat(
+                                start_str.split("T")[0]
+                            ).date()
+                            component["DTSTART"] = start_date
+                        else:
+                            start_dt = dt.datetime.fromisoformat(
+                                start_str.replace("Z", "+00:00")
+                            )
+                            component["DTSTART"] = start_dt
+
+                    if "end_datetime" in event_data:
+                        end_str = event_data["end_datetime"]
+                        all_day = event_data.get("all_day", False)
+                        if all_day:
+                            end_date = dt.datetime.fromisoformat(
+                                end_str.split("T")[0]
+                            ).date()
+                            component["DTEND"] = end_date
+                        else:
+                            end_dt = dt.datetime.fromisoformat(
+                                end_str.replace("Z", "+00:00")
+                            )
+                            component["DTEND"] = end_dt
+
+                    # Handle categories
+                    if "categories" in event_data:
+                        categories = event_data["categories"]
+                        if categories:
+                            component["CATEGORIES"] = categories.split(",")
+
+                    # Handle recurrence
+                    if "recurring" in event_data:
+                        if event_data["recurring"] and "recurrence_rule" in event_data:
+                            recurrence_rule = event_data["recurrence_rule"]
+                            if recurrence_rule:
+                                component["RRULE"] = vRecur.from_ical(recurrence_rule)
+                        elif not event_data["recurring"]:
+                            # Remove recurrence if set to False
+                            if "RRULE" in component:
+                                del component["RRULE"]
+
+                    # Handle attendees
+                    if "attendees" in event_data:
+                        attendees = event_data["attendees"]
+                        # Remove existing attendees
+                        component.pop("ATTENDEE", None)
+                        if attendees:
+                            for email in attendees.split(","):
+                                if email.strip():
+                                    component.add("ATTENDEE", f"mailto:{email.strip()}")
+
+                    # Update timestamps in proper iCal format
+                    from icalendar import vDDDTypes
+
+                    now = dt.datetime.now(dt.UTC)
+                    component["LAST-MODIFIED"] = vDDDTypes(now)
+                    component["DTSTAMP"] = vDDDTypes(now)
+
+                    # Preserve all other existing properties (X-*, ORGANIZER, COMMENT, GEO, etc.)
+                    # by not touching them - they remain in the component
+
+                    break
+
+            return cal.to_ical().decode("utf-8")
+
+        except Exception as e:
+            logger.error(f"Error merging iCal properties: {e}")
+            # Fallback to creating new iCal
+            return self._create_ical_event(event_data, event_uid)