iflow-mcp_democratize-technology-chronos-mcp 2.0.0__py3-none-any.whl

chronos_mcp/rrule.py

@@ -0,0 +1,259 @@
+"""RRULE validation and parsing for recurring events.
+
+This module provides utilities for validating and working with
+iCalendar RRULE (recurrence rule) strings used in recurring events.
+"""
+
+import logging
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional, Tuple
+
+from dateutil.rrule import DAILY, MONTHLY, WEEKLY, YEARLY, rrulestr
+
+logger = logging.getLogger(__name__)
+
+# Maximum values for safety
+MAX_COUNT = 365  # Maximum number of occurrences
+MAX_YEARS_AHEAD = 2  # Maximum years into the future
+MIN_INTERVAL_SECONDS = 3600  # Minimum 1 hour between occurrences
+MAX_INSTANCES_TO_EXPAND = 1000  # Maximum instances to expand at once
+
+
+class RRuleValidator:
+    """Validate and parse RRULE strings for recurring events."""
+
+    # Allowed frequencies (no SECONDLY or MINUTELY for performance)
+    ALLOWED_FREQUENCIES = {
+        "DAILY": DAILY,
+        "WEEKLY": WEEKLY,
+        "MONTHLY": MONTHLY,
+        "YEARLY": YEARLY,
+    }
+
+    @classmethod
+    def validate_rrule(cls, rrule_string: str) -> Tuple[bool, Optional[str]]:
+        """
+        Validate an RRULE string for safety and correctness.
+
+        Args:
+            rrule_string: The RRULE string to validate
+
+        Returns:
+            Tuple of (is_valid, error_message)
+        """
+        if not rrule_string:
+            return False, "RRULE cannot be empty"
+
+        try:
+            # Basic format check
+            if not rrule_string.startswith("FREQ="):
+                return False, "RRULE must start with FREQ="
+
+            # Parse the rule to check validity
+            rule = rrulestr(rrule_string)
+
+            # Extract frequency
+            freq_str = None
+            for part in rrule_string.split(";"):
+                if part.startswith("FREQ="):
+                    freq_str = part.split("=")[1]
+                    break
+
+            if freq_str not in cls.ALLOWED_FREQUENCIES:
+                return (
+                    False,
+                    f"Frequency {freq_str} not allowed. Use: {', '.join(cls.ALLOWED_FREQUENCIES.keys())}",
+                )
+
+            # Check for end condition (COUNT or UNTIL)
+            has_count = "COUNT=" in rrule_string
+            has_until = "UNTIL=" in rrule_string
+
+            if not has_count and not has_until:
+                return (
+                    False,
+                    "RRULE must have COUNT or UNTIL to prevent infinite recurrence",
+                )
+
+            # Validate COUNT if present
+            if has_count:
+                count_value = cls._extract_value(rrule_string, "COUNT")
+                if count_value:
+                    try:
+                        count = int(count_value)
+                        if count > MAX_COUNT:
+                            return False, f"COUNT cannot exceed {MAX_COUNT}"
+                        if count < 1:
+                            return False, "COUNT must be at least 1"
+                    except ValueError:
+                        return False, "COUNT must be a valid integer"
+
+            # Validate UNTIL if present
+            if has_until:
+                until_value = cls._extract_value(rrule_string, "UNTIL")
+                if until_value:
+                    try:
+                        # Parse the until date
+                        if "T" in until_value:
+                            until_dt = datetime.strptime(until_value, "%Y%m%dT%H%M%SZ")
+                        else:
+                            until_dt = datetime.strptime(until_value, "%Y%m%d")
+
+                        # Ensure it's timezone aware
+                        if until_dt.tzinfo is None:
+                            until_dt = until_dt.replace(tzinfo=timezone.utc)
+
+                        # Check it's not too far in the future
+                        now = datetime.now(timezone.utc)
+                        max_future = now.replace(year=now.year + MAX_YEARS_AHEAD)
+
+                        if until_dt > max_future:
+                            return (
+                                False,
+                                f"UNTIL date cannot be more than {MAX_YEARS_AHEAD} years in the future",
+                            )
+
+                    except ValueError:
+                        return (
+                            False,
+                            "UNTIL must be a valid date in YYYYMMDD or YYYYMMDDTHHMMSSZ format",
+                        )
+
+            # Validate INTERVAL if present
+            if "INTERVAL=" in rrule_string:
+                interval_value = cls._extract_value(rrule_string, "INTERVAL")
+                if interval_value:
+                    try:
+                        interval = int(interval_value)
+                        if interval < 1:
+                            return False, "INTERVAL must be at least 1"
+                        # Check minimum interval based on frequency
+                        if freq_str == "DAILY" and interval > 365:
+                            return False, "Daily INTERVAL cannot exceed 365"
+                    except ValueError:
+                        return False, "INTERVAL must be a valid integer"
+
+            return True, None
+
+        except Exception as e:
+            logger.error(f"Error validating RRULE: {str(e)}")
+            return False, f"Invalid RRULE format: {str(e)}"
+
+    @staticmethod
+    def _extract_value(rrule_string: str, param: str) -> Optional[str]:
+        """Extract a parameter value from an RRULE string."""
+        for part in rrule_string.split(";"):
+            if part.startswith(f"{param}="):
+                return part.split("=")[1]
+        return None
+
+    @classmethod
+    def expand_occurrences(
+        cls,
+        rrule_string: str,
+        start_date: datetime,
+        end_date: Optional[datetime] = None,
+        limit: int = MAX_INSTANCES_TO_EXPAND,
+    ) -> List[datetime]:
+        """
+        Expand recurring rule to individual occurrences.
+        Args:
+            rrule_string: The RRULE string
+            start_date: Start date for the recurrence
+            end_date: Optional end date to limit occurrences
+            limit: Maximum number of occurrences to return
+
+        Returns:
+            List of datetime objects representing occurrences
+        """
+        try:
+            # Ensure start_date has timezone
+            if start_date.tzinfo is None:
+                start_date = start_date.replace(tzinfo=timezone.utc)
+
+            # Parse the rule
+            rule = rrulestr(rrule_string, dtstart=start_date)
+
+            # Generate occurrences
+            occurrences = []
+            for i, occurrence in enumerate(rule):
+                if i >= limit:
+                    break
+
+                if end_date and occurrence > end_date:
+                    break
+
+                occurrences.append(occurrence)
+
+            return occurrences
+
+        except Exception as e:
+            logger.error(f"Error expanding RRULE occurrences: {str(e)}")
+            return []
+
+    @classmethod
+    def get_rrule_info(cls, rrule_string: str) -> Dict[str, Any]:
+        """
+        Extract information from an RRULE string.
+
+        Args:
+            rrule_string: The RRULE string to parse
+
+        Returns:
+            Dictionary with RRULE components
+        """
+        info = {
+            "frequency": None,
+            "interval": 1,
+            "count": None,
+            "until": None,
+            "byday": None,
+            "bymonthday": None,
+            "bymonth": None,
+        }
+
+        for part in rrule_string.split(";"):
+            if "=" in part:
+                key, value = part.split("=", 1)
+                key_lower = key.lower()
+
+                if key == "FREQ":
+                    info["frequency"] = value
+                elif key == "INTERVAL":
+                    info["interval"] = int(value)
+                elif key == "COUNT":
+                    info["count"] = int(value)
+                elif key == "UNTIL":
+                    info["until"] = value
+                elif key == "BYDAY":
+                    info["byday"] = value.split(",")
+                elif key == "BYMONTHDAY":
+                    info["bymonthday"] = [int(d) for d in value.split(",")]
+                elif key == "BYMONTH":
+                    info["bymonth"] = [int(m) for m in value.split(",")]
+
+        return info
+
+
+# Common RRULE patterns for convenience
+class RRuleTemplates:
+    """Common RRULE templates for recurring events."""
+
+    # Daily patterns
+    DAILY_WEEKDAYS = "FREQ=DAILY;BYDAY=MO,TU,WE,TH,FR"
+    DAILY_FOREVER = "FREQ=DAILY"  # Needs COUNT or UNTIL added
+
+    # Weekly patterns
+    WEEKLY_ON_DAY = "FREQ=WEEKLY;BYDAY={day}"  # Replace {day} with MO, TU, etc.
+    WEEKLY_MULTIPLE_DAYS = (
+        "FREQ=WEEKLY;BYDAY={days}"  # Replace {days} with comma-separated
+    )
+
+    # Monthly patterns
+    MONTHLY_ON_DATE = "FREQ=MONTHLY;BYMONTHDAY={day}"  # Replace {day} with 1-31
+    MONTHLY_LAST_DAY = "FREQ=MONTHLY;BYMONTHDAY=-1"
+    MONTHLY_FIRST_WEEKDAY = "FREQ=MONTHLY;BYDAY=1{day}"  # e.g., 1MO for first Monday
+
+    # Yearly patterns
+    YEARLY_ON_DATE = "FREQ=YEARLY"
+    YEARLY_ON_MONTH_DAY = "FREQ=YEARLY;BYMONTH={month};BYMONTHDAY={day}"

chronos_mcp/search.py

@@ -0,0 +1,315 @@
+"""CalDAV component search functionality for Chronos MCP (Events, Tasks, Journals)."""
+
+import re
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any, Dict, List, Optional, Tuple
+
+
+@dataclass
+class SearchOptions:
+    """Options for CalDAV component search functionality."""
+
+    query: str
+    fields: List[str]
+    component_types: List[str] = field(default_factory=lambda: ["VEVENT"])
+    case_sensitive: bool = False
+    match_type: str = "contains"
+    use_regex: bool = False
+    date_start: Optional[datetime] = None
+    date_end: Optional[datetime] = None
+    max_results: Optional[int] = None
+
+    def __post_init__(self):
+        valid_types = ["contains", "starts_with", "ends_with", "exact", "regex"]
+        if self.match_type not in valid_types:
+            raise ValueError(f"match_type must be one of {valid_types}")
+
+        valid_components = ["VEVENT", "VTODO", "VJOURNAL"]
+        for comp_type in self.component_types:
+            if comp_type not in valid_components:
+                raise ValueError(f"component_type must be one of {valid_components}")
+
+        # Set default fields based on component types if not provided
+        if not self.fields:
+            self.fields = self._get_default_fields()
+
+        if self.use_regex or self.match_type == "regex":
+            flags = 0 if self.case_sensitive else re.IGNORECASE
+            self.pattern = re.compile(self.query, flags)
+
+    def _get_default_fields(self) -> List[str]:
+        """Get default search fields based on component types."""
+        fields = set(["summary", "description"])  # Common fields
+
+        if "VEVENT" in self.component_types:
+            fields.update(["location"])
+
+        if "VTODO" in self.component_types:
+            fields.update(["due", "priority", "status", "percent_complete"])
+
+        if "VJOURNAL" in self.component_types:
+            fields.update(["dtstart", "categories"])
+
+        return list(fields)
+
+
+def _matches_component_type(component: Dict[str, Any], options: SearchOptions) -> bool:
+    """Check if component matches the requested component types."""
+    component_type = component.get(
+        "component_type", "VEVENT"
+    )  # Default to VEVENT for backward compatibility
+
+    # For legacy support, try to infer component type from fields
+    if component_type == "VEVENT" and not component.get("component_type"):
+        if (
+            "due" in component
+            or "priority" in component
+            or "percent_complete" in component
+        ):
+            component_type = "VTODO"
+        elif (
+            "dtstart" in component
+            and "categories" in component
+            and not component.get("dtend")
+        ):
+            component_type = "VJOURNAL"
+
+    return component_type in options.component_types
+
+
+def search_components(
+    components: List[Dict[str, Any]], options: SearchOptions
+) -> List[Dict[str, Any]]:
+    """Search CalDAV components (events, tasks, journals) based on provided options."""
+    if not options.query and not (options.date_start or options.date_end):
+        # Filter by component type even if no query
+        return [comp for comp in components if _matches_component_type(comp, options)]
+
+    def matches_text(component: Dict[str, Any]) -> bool:
+        if not options.query:
+            return True
+
+        for field in options.fields:
+            value = component.get(field, "")
+            if value is None:
+                continue
+
+            # Handle special field formatting
+            if field == "categories" and isinstance(value, list):
+                value_str = " ".join(str(v) for v in value)
+            elif field in ["priority", "percent_complete"] and value is not None:
+                value_str = str(value)
+            else:
+                value_str = str(value)
+
+            if not options.case_sensitive:
+                value_str = value_str.lower()
+                query = options.query.lower()
+            else:
+                query = options.query
+
+            if options.use_regex or options.match_type == "regex":
+                if options.pattern.search(value_str):
+                    return True
+            elif options.match_type == "contains":
+                if query in value_str:
+                    return True
+            elif options.match_type == "starts_with":
+                if value_str.startswith(query):
+                    return True
+            elif options.match_type == "ends_with":
+                if value_str.endswith(query):
+                    return True
+            elif options.match_type == "exact":
+                if value_str == query:
+                    return True
+
+        return False
+
+    def matches_date(component: Dict[str, Any]) -> bool:
+        if not (options.date_start or options.date_end):
+            return True
+
+        # Try different date fields based on component type
+        date_field = None
+        if component.get("component_type") == "VTODO" or "due" in component:
+            date_field = component.get("due")
+        elif component.get("component_type") == "VJOURNAL" or (
+            "dtstart" in component and not component.get("dtend")
+        ):
+            date_field = component.get("dtstart")
+        else:  # VEVENT
+            date_field = component.get("dtstart") or component.get("start")
+
+        if not date_field:
+            return False
+
+        if isinstance(date_field, str):
+            date_field = datetime.fromisoformat(date_field.replace("Z", "+00:00"))
+
+        if options.date_start and date_field < options.date_start:
+            return False
+        if options.date_end and date_field > options.date_end:
+            return False
+
+        return True
+
+    results = [
+        component
+        for component in components
+        if _matches_component_type(component, options)
+        and matches_text(component)
+        and matches_date(component)
+    ]
+
+    if options.max_results:
+        results = results[: options.max_results]
+
+    return results
+
+
+def calculate_relevance_score(
+    component: Dict[str, Any], options: SearchOptions, current_time: datetime = None
+) -> float:
+    """Calculate relevance score for search ranking."""
+    if current_time is None:
+        current_time = datetime.now()
+
+    score = 0.0
+    query = options.query.lower() if not options.case_sensitive else options.query
+
+    field_weights = {
+        "summary": 3.0,
+        "description": 2.0,
+        "location": 1.0,
+        "due": 2.5,
+        "priority": 1.5,
+        "status": 1.0,
+        "percent_complete": 1.0,
+        "dtstart": 2.0,
+        "categories": 1.5,
+    }
+
+    for field in options.fields:
+        if field not in field_weights:
+            continue
+
+        value = component.get(field, "")
+        if not value:
+            continue
+
+        # Handle special field formatting for scoring
+        if field == "categories" and isinstance(value, list):
+            value_str = " ".join(str(v) for v in value)
+        elif field in ["priority", "percent_complete"] and value is not None:
+            value_str = str(value)
+        else:
+            value_str = str(value)
+
+        if not options.case_sensitive:
+            value_str = value_str.lower()
+
+        field_score = 0.0
+
+        if options.use_regex or options.match_type == "regex":
+            matches = list(options.pattern.finditer(value_str))
+            if matches:
+                field_score = 2.0 * len(matches)
+                first_match_pos = matches[0].start()
+                position_factor = 1.0 - (first_match_pos / max(len(value_str), 1))
+                field_score *= 1.0 + position_factor * 0.5
+        else:
+            if options.match_type == "exact" and value_str == query:
+                field_score = 5.0
+            elif options.match_type == "starts_with" and value_str.startswith(query):
+                field_score = 3.0
+            elif options.match_type == "contains" or query in value_str:
+                occurrences = value_str.count(query)
+                if occurrences > 0:
+                    field_score = 1.0 * occurrences
+                    first_pos = value_str.find(query)
+                    position_factor = 1.0 - (first_pos / max(len(value_str), 1))
+                    field_score *= 1.0 + position_factor * 0.5
+
+        score += field_score * field_weights.get(field, 1.0)
+
+    # Recency boost - use appropriate date field based on component type
+    date_field = None
+    if component.get("component_type") == "VTODO" or "due" in component:
+        date_field = component.get("due")
+    elif component.get("component_type") == "VJOURNAL" or (
+        "dtstart" in component and not component.get("dtend")
+    ):
+        date_field = component.get("dtstart")
+    else:  # VEVENT
+        date_field = component.get("dtstart") or component.get("start")
+
+    if date_field:
+        if isinstance(date_field, str):
+            date_field = datetime.fromisoformat(date_field.replace("Z", "+00:00"))
+
+        days_diff = abs((current_time - date_field).days)
+        if days_diff <= 30:
+            recency_boost = 0.1 * (1.0 - days_diff / 30.0)
+            score *= 1.0 + recency_boost
+
+    return score
+
+
+def search_components_ranked(
+    components: List[Dict[str, Any]], options: SearchOptions
+) -> List[Tuple[Dict[str, Any], float]]:
+    """Search CalDAV components and return them with relevance scores."""
+    matching_components = search_components(components, options)
+
+    scored_components = []
+    for component in matching_components:
+        score = calculate_relevance_score(component, options)
+        scored_components.append((component, score))
+
+    scored_components.sort(key=lambda x: x[1], reverse=True)
+
+    if options.max_results:
+        scored_components = scored_components[: options.max_results]
+
+    return scored_components
+
+
+# Backward compatibility functions
+def search_events(
+    events: List[Dict[str, Any]], options: SearchOptions
+) -> List[Dict[str, Any]]:
+    """Search events - backward compatibility wrapper."""
+    # Ensure we're only searching events for backward compatibility
+    event_options = SearchOptions(
+        query=options.query,
+        fields=options.fields,
+        component_types=["VEVENT"],
+        case_sensitive=options.case_sensitive,
+        match_type=options.match_type,
+        use_regex=options.use_regex,
+        date_start=options.date_start,
+        date_end=options.date_end,
+        max_results=options.max_results,
+    )
+    return search_components(events, event_options)
+
+
+def search_events_ranked(
+    events: List[Dict[str, Any]], options: SearchOptions
+) -> List[Tuple[Dict[str, Any], float]]:
+    """Search events and return them with relevance scores - backward compatibility wrapper."""
+    # Ensure we're only searching events for backward compatibility
+    event_options = SearchOptions(
+        query=options.query,
+        fields=options.fields,
+        component_types=["VEVENT"],
+        case_sensitive=options.case_sensitive,
+        match_type=options.match_type,
+        use_regex=options.use_regex,
+        date_start=options.date_start,
+        date_end=options.date_end,
+        max_results=options.max_results,
+    )
+    return search_components_ranked(events, event_options)

chronos_mcp/server.py

@@ -0,0 +1,121 @@
+"""
+Chronos MCP Server - Advanced CalDAV Management
+"""
+
+from fastmcp import FastMCP
+
+from .accounts import AccountManager
+from .bulk import BulkOperationManager
+from .calendars import CalendarManager
+from .config import ConfigManager
+from .events import EventManager
+from .journals import JournalManager
+from .logging_config import setup_logging
+from .tasks import TaskManager
+from .tools import register_all_tools
+
+logger = setup_logging()
+
+mcp = FastMCP("chronos-mcp")
+
+logger.info("Initializing Chronos MCP Server...")
+
+try:
+    config_manager = ConfigManager()
+    account_manager = AccountManager(config_manager)
+    calendar_manager = CalendarManager(account_manager)
+    event_manager = EventManager(calendar_manager)
+    task_manager = TaskManager(calendar_manager)
+    journal_manager = JournalManager(calendar_manager)
+    bulk_manager = BulkOperationManager(
+        event_manager=event_manager,
+        task_manager=task_manager,
+        journal_manager=journal_manager,
+    )
+    logger.info("All managers initialized successfully")
+
+    managers = {
+        "config_manager": config_manager,
+        "account_manager": account_manager,
+        "calendar_manager": calendar_manager,
+        "event_manager": event_manager,
+        "task_manager": task_manager,
+        "journal_manager": journal_manager,
+        "bulk_manager": bulk_manager,
+    }
+
+    register_all_tools(mcp, managers)
+    logger.info("All tools registered successfully")
+
+except Exception as e:
+    logger.error(f"Error initializing Chronos MCP Server: {e}")
+    raise
+
+
+# Export all tools for backwards compatibility
+# This allows tests and existing code to import from server.py
+from .tools.accounts import add_account, list_accounts, remove_account, test_account
+from .tools.bulk import (
+    bulk_create_events,
+    bulk_create_journals,
+    bulk_create_tasks,
+    bulk_delete_events,
+    bulk_delete_journals,
+    bulk_delete_tasks,
+)
+from .tools.calendars import create_calendar, delete_calendar, list_calendars
+from .tools.events import (
+    create_event,
+    create_recurring_event,
+    delete_event,
+    get_events_range,
+    search_events,
+    update_event,
+)
+from .tools.journals import (
+    create_journal,
+    delete_journal,
+    list_journals,
+    update_journal,
+)
+from .tools.tasks import create_task, delete_task, list_tasks, update_task
+
+__all__ = [
+    # Account tools
+    "add_account",
+    "list_accounts",
+    "remove_account",
+    "test_account",
+    # Calendar tools
+    "list_calendars",
+    "create_calendar",
+    "delete_calendar",
+    # Event tools
+    "create_event",
+    "get_events_range",
+    "delete_event",
+    "update_event",
+    "create_recurring_event",
+    "search_events",
+    # Task tools
+    "create_task",
+    "list_tasks",
+    "update_task",
+    "delete_task",
+    # Journal tools
+    "create_journal",
+    "list_journals",
+    "update_journal",
+    "delete_journal",
+    # Bulk tools
+    "bulk_create_events",
+    "bulk_delete_events",
+    "bulk_create_tasks",
+    "bulk_delete_tasks",
+    "bulk_create_journals",
+    "bulk_delete_journals",
+]
+
+# Main entry point for running the server
+if __name__ == "__main__":
+    mcp.run()