iflow-mcp_excelsier-things3-enhanced-mcp 1.0.0__py3-none-any.whl

things_mcp/applescript_bridge.py

@@ -0,0 +1,335 @@
+#!/usr/bin/env python3
+import subprocess
+import logging
+from typing import Optional, List, Dict, Any, Union
+
+logger = logging.getLogger(__name__)
+
+def run_applescript(script: str) -> Union[str, bool]:
+    """Run an AppleScript command and return the result.
+    
+    Args:
+        script: The AppleScript code to execute
+        
+    Returns:
+        The result of the AppleScript execution, or False if it failed
+    """
+    try:
+        result = subprocess.run(['osascript', '-e', script], 
+                              capture_output=True, text=True)
+        
+        if result.returncode != 0:
+            logger.error(f"AppleScript error: {result.stderr}")
+            return False
+        
+        return result.stdout.strip()
+    except Exception as e:
+        logger.error(f"Error running AppleScript: {str(e)}")
+        return False
+
+def add_todo_direct(title: str, notes: Optional[str] = None, when: Optional[str] = None,
+                   tags: Optional[List[str]] = None, list_title: Optional[str] = None) -> str:
+    """Add a todo to Things directly using AppleScript.
+    
+    This bypasses URL schemes entirely to avoid encoding issues.
+    
+    Args:
+        title: Title of the todo
+        notes: Notes for the todo
+        when: When to schedule the todo (today, tomorrow, evening, anytime, someday)
+        tags: Tags to apply to the todo
+        list_title: Name of project/area to add to
+        
+    Returns:
+        ID of the created todo if successful, False otherwise
+    """
+    # Build the AppleScript command
+    script_parts = ['tell application "Things3"']
+    
+    # Create the todo with properties
+    properties = []
+    properties.append(f'name:"{escape_applescript_string(title)}"')
+    
+    if notes:
+        properties.append(f'notes:"{escape_applescript_string(notes)}"')
+    
+    # Create with properties in the right way
+    script_parts.append(f'set newTodo to make new to do with properties {{{", ".join(properties)}}}')
+    
+    # Add scheduling
+    if when:
+        when_mapping = {
+            'today': '',  # Default is today, no need to set
+            'tomorrow': 'set activation date of newTodo to ((current date) + 1 * days)',
+            'evening': '',  # Default is today, no need to set
+            'anytime': '',  # Default
+            'someday': 'set status of newTodo to someday'
+        }
+        
+        if when in when_mapping:
+            if when_mapping[when]:
+                script_parts.append(when_mapping[when])
+        else:
+            # For date handling, it's safest to just log it and not try to set it
+            # This avoids AppleScript date formatting issues
+            logger.warning(f"Custom date format '{when}' not supported, defaulting to today")
+    
+    # Add tags if provided
+    if tags and len(tags) > 0:
+        for tag in tags:
+            script_parts.append(f'tell newTodo to make new tag with properties {{name:"{escape_applescript_string(tag)}"}}')
+    
+    # Add to a specific project/area if specified
+    if list_title:
+        script_parts.append(f'set project_name to "{escape_applescript_string(list_title)}"')
+        script_parts.append('try')
+        script_parts.append('  set target_project to first project whose name is project_name')
+        script_parts.append('  set project of newTodo to target_project')
+        script_parts.append('on error')
+        script_parts.append('  -- Project not found, try area')
+        script_parts.append('  try')
+        script_parts.append('    set target_area to first area whose name is project_name')
+        script_parts.append('    set area of newTodo to target_area')
+        script_parts.append('  on error')
+        script_parts.append('    -- Neither project nor area found, todo will remain in inbox')
+        script_parts.append('  end try')
+        script_parts.append('end try')
+    
+    # Get the ID of the created todo
+    script_parts.append('return id of newTodo')
+    
+    # Close the tell block
+    script_parts.append('end tell')
+    
+    # Execute the script
+    script = '\n'.join(script_parts)
+    logger.debug(f"Executing AppleScript: {script}")
+    
+    result = run_applescript(script)
+    if result:
+        logger.info(f"Successfully created todo with ID: {result}")
+        return result
+    else:
+        logger.error("Failed to create todo")
+        return False
+
+def escape_applescript_string(text: str) -> str:
+    """Escape special characters in an AppleScript string.
+    
+    Args:
+        text: The string to escape
+        
+    Returns:
+        The escaped string
+    """
+    if not text:
+        return ""
+    
+    # Replace any "+" with spaces first
+    text = text.replace("+", " ")
+    
+    # Escape quotes by doubling them (AppleScript style)
+    return text.replace('"', '""')
+
+def update_todo_direct(id: str, title: Optional[str] = None, notes: Optional[str] = None,
+                     when: Optional[str] = None, deadline: Optional[str] = None,
+                     tags: Optional[Union[List[str], str]] = None, add_tags: Optional[Union[List[str], str]] = None,
+                     checklist_items: Optional[List[str]] = None, completed: Optional[bool] = None, 
+                     canceled: Optional[bool] = None) -> bool:
+    """Update a todo directly using AppleScript.
+    
+    This bypasses URL schemes entirely to avoid authentication issues.
+    
+    Args:
+        id: The ID of the todo to update
+        title: New title for the todo
+        notes: New notes for the todo
+        when: New schedule for the todo (today, tomorrow, evening, anytime, someday, or YYYY-MM-DD)
+        deadline: New deadline for the todo (YYYY-MM-DD)
+        tags: New tags for the todo (replaces existing tags)
+        add_tags: Tags to add to the todo (preserves existing tags)
+        checklist_items: Checklist items to set for the todo (replaces existing items)
+        completed: Mark as completed
+        canceled: Mark as canceled
+    
+    Returns:
+        True if successful, False otherwise
+    """
+    import re
+    
+    # Build the AppleScript command to find and update the todo
+    script_parts = ['tell application "Things3"']
+    script_parts.append('try')
+    script_parts.append(f'    set theTodo to to do id "{id}"')
+    
+    # Update properties one at a time
+    if title:
+        script_parts.append(f'    set name of theTodo to "{escape_applescript_string(title)}"')
+    
+    if notes:
+        script_parts.append(f'    set notes of theTodo to "{escape_applescript_string(notes)}"')
+    
+    # Handle date-related properties
+    if when:
+        # Check if when is a date in YYYY-MM-DD format
+        is_date_format = re.match(r'^\d{4}-\d{2}-\d{2}$', when)
+        
+        # Simple mapping of common 'when' values to AppleScript commands
+        if when == 'today':
+            script_parts.append('    move theTodo to list "Today"')
+        elif when == 'tomorrow':
+            script_parts.append('    set activation date of theTodo to ((current date) + (1 * days))')
+            script_parts.append('    move theTodo to list "Upcoming"')
+        elif when == 'evening':
+            script_parts.append('    move theTodo to list "Evening"')
+        elif when == 'anytime':
+            script_parts.append('    move theTodo to list "Anytime"')
+        elif when == 'someday':
+            script_parts.append('    move theTodo to list "Someday"')
+        elif is_date_format:
+            # Handle YYYY-MM-DD format dates
+            year, month, day = when.split('-')
+            script_parts.append(f'''
+    -- Set activation date with direct date string
+    set dateString to "{when}"
+    set newDate to date dateString
+    set activation date of theTodo to newDate
+    -- Move to the Upcoming list
+    move theTodo to list "Upcoming"
+''')
+        else:
+            # For other formats, just log a warning and don't try to set it
+            logger.warning(f"Schedule format '{when}' not directly supported in this simplified version")
+    
+    if deadline:
+        # Check if deadline is in YYYY-MM-DD format
+        if re.match(r'^\d{4}-\d{2}-\d{2}$', deadline):
+            year, month, day = deadline.split('-')
+            script_parts.append(f'''
+    -- Set deadline with direct date string
+    set deadlineString to "{deadline}"
+    set deadlineDate to date deadlineString
+    set deadline of theTodo to deadlineDate
+''')
+        else:
+            logger.warning(f"Invalid deadline format: {deadline}. Expected YYYY-MM-DD")
+    
+    # Handle tags (clearing and adding new ones)
+    if tags is not None:
+        # Convert string tags to list if needed
+        if isinstance(tags, str):
+            tags = [tags]
+            
+        if tags:
+            # Clear existing tags first
+            script_parts.append('    -- Clear existing tags')
+            script_parts.append('    set tag_names of theTodo to {}')
+            
+            # Simplified tag handling
+            import json
+            tags_json = json.dumps(tags)
+            script_parts.append(f'''
+    -- Set tags using a list
+    set tagNameList to {tags_json}
+    -- Clear existing tags
+    set oldTags to tags of theTodo
+    repeat with t from (count of oldTags) to 1 by -1
+        delete item t of oldTags
+    end repeat
+    -- Add new tags
+    repeat with t from 1 to (count of tagNameList)
+        set tagText to item t of tagNameList
+        tell theTodo
+            set newTag to make new tag
+            set name of newTag to tagText
+        end tell
+    end repeat
+''')
+        else:
+            # Clear all tags if empty list provided
+            script_parts.append('    -- Clear all tags')
+            script_parts.append('    set tag_names of theTodo to {}')
+    
+    # Handle adding tags without replacing existing ones
+    if add_tags is not None:
+        # Convert string to list if needed
+        if isinstance(add_tags, str):
+            add_tags = [add_tags]
+            
+        for tag in add_tags:
+            tag_name = escape_applescript_string(tag)
+            script_parts.append(f'''
+            -- Add tag {tag_name} if it doesn't exist
+            set tagFound to false
+            repeat with t in tags of theTodo
+                if name of t is "{tag_name}" then
+                    set tagFound to true
+                    exit repeat
+                end if
+            end repeat
+            if not tagFound then
+                tell theTodo to make new tag with properties {{name:"{tag_name}"}}
+            end if
+            ''')
+            
+    # Handle checklist items - simplified approach
+    if checklist_items is not None:
+        # Convert string to list if needed
+        if isinstance(checklist_items, str):
+            checklist_items = checklist_items.split('\n')
+            
+        if checklist_items:
+            # For simplicity, we'll use JSON to pass checklist items
+            import json
+            items_json = json.dumps([item for item in checklist_items])
+            script_parts.append(f'''
+    -- Clear and set checklist items
+    set oldItems to check list items of theTodo
+    repeat with i from (count of oldItems) to 1 by -1
+        delete item i of oldItems
+    end repeat
+    
+    set itemList to {items_json}
+    repeat with i from 1 to (count of itemList)
+        set itemText to item i of itemList
+        tell theTodo
+            set newItem to make new check list item
+            set name of newItem to itemText
+        end tell
+    end repeat
+''')
+    
+    # Handle completion status - use completion date approach
+    if completed is not None:
+        if completed:
+            script_parts.append('    set status of theTodo to completed')
+        else:
+            script_parts.append('    set status of theTodo to open')
+    
+    # Handle canceled status
+    if canceled is not None:
+        if canceled:
+            script_parts.append('    set status of theTodo to canceled')
+        else:
+            script_parts.append('    set status of theTodo to open')
+    
+    # Return true on success
+    script_parts.append('    return true')
+    script_parts.append('on error errMsg')
+    script_parts.append('    log "Error updating todo: " & errMsg')
+    script_parts.append('    return false')
+    script_parts.append('end try')
+    script_parts.append('end tell')
+    
+    # Execute the script
+    script = '\n'.join(script_parts)
+    logger.info(f"Executing AppleScript for update_todo_direct: \n{script}")
+    
+    result = run_applescript(script)
+    
+    if result == "true":
+        logger.info(f"Successfully updated todo with ID: {id}")
+        return True
+    else:
+        logger.error(f"AppleScript update_todo_direct failed: {result}")
+        return False

things_mcp/cache.py

@@ -0,0 +1,240 @@
+#!/usr/bin/env python3
+"""
+Caching module for Things MCP server.
+Provides intelligent caching for frequently accessed data to improve performance.
+"""
+import time
+import json
+import hashlib
+import logging
+from typing import Any, Dict, Optional, Callable, Tuple
+from functools import wraps
+from threading import Lock
+
+logger = logging.getLogger(__name__)
+
+class ThingsCache:
+    """
+    Thread-safe cache for Things data with TTL support.
+    """
+    
+    def __init__(self, default_ttl: int = 300):  # 5 minutes default
+        """
+        Initialize the cache.
+        
+        Args:
+            default_ttl: Default time-to-live for cache entries in seconds
+        """
+        self.cache: Dict[str, Tuple[Any, float]] = {}
+        self.default_ttl = default_ttl
+        self.lock = Lock()
+        self.hit_count = 0
+        self.miss_count = 0
+        
+    def _make_key(self, operation: str, **kwargs) -> str:
+        """Generate a cache key from operation and parameters."""
+        # Sort kwargs to ensure consistent keys
+        sorted_params = json.dumps(kwargs, sort_keys=True)
+        key_string = f"{operation}:{sorted_params}"
+        # Use hash for shorter keys
+        return hashlib.md5(key_string.encode()).hexdigest()
+    
+    def get(self, operation: str, **kwargs) -> Optional[Any]:
+        """
+        Get a value from cache if it exists and hasn't expired.
+        
+        Args:
+            operation: The operation name
+            **kwargs: Parameters for the operation
+            
+        Returns:
+            Cached value if available and valid, None otherwise
+        """
+        key = self._make_key(operation, **kwargs)
+        
+        with self.lock:
+            if key in self.cache:
+                value, expiry_time = self.cache[key]
+                if time.time() < expiry_time:
+                    self.hit_count += 1
+                    logger.debug(f"Cache hit for {operation}: {key}")
+                    return value
+                else:
+                    # Expired, remove it
+                    del self.cache[key]
+                    logger.debug(f"Cache expired for {operation}: {key}")
+            
+            self.miss_count += 1
+            return None
+    
+    def set(self, operation: str, value: Any, ttl: Optional[int] = None, **kwargs) -> None:
+        """
+        Set a value in the cache.
+        
+        Args:
+            operation: The operation name
+            value: The value to cache
+            ttl: Time-to-live in seconds (uses default if not specified)
+            **kwargs: Parameters for the operation
+        """
+        key = self._make_key(operation, **kwargs)
+        ttl = ttl if ttl is not None else self.default_ttl
+        expiry_time = time.time() + ttl
+        
+        with self.lock:
+            self.cache[key] = (value, expiry_time)
+            logger.debug(f"Cache set for {operation}: {key}, TTL: {ttl}s")
+    
+    def invalidate(self, operation: Optional[str] = None, **kwargs) -> None:
+        """
+        Invalidate cache entries.
+        
+        Args:
+            operation: If specified, only invalidate entries for this operation
+            **kwargs: If specified with operation, invalidate specific entry
+        """
+        with self.lock:
+            if operation and kwargs:
+                # Invalidate specific entry
+                key = self._make_key(operation, **kwargs)
+                if key in self.cache:
+                    del self.cache[key]
+                    logger.debug(f"Invalidated specific cache entry: {key}")
+            elif operation:
+                # Invalidate all entries for an operation
+                keys_to_remove = [k for k in self.cache.keys() 
+                                 if k.startswith(hashlib.md5(f"{operation}:".encode()).hexdigest()[:8])]
+                for key in keys_to_remove:
+                    del self.cache[key]
+                logger.debug(f"Invalidated {len(keys_to_remove)} cache entries for operation: {operation}")
+            else:
+                # Clear entire cache
+                self.cache.clear()
+                logger.info("Cleared entire cache")
+    
+    def cleanup_expired(self) -> int:
+        """Remove expired entries from cache. Returns number of entries removed."""
+        current_time = time.time()
+        removed_count = 0
+        
+        with self.lock:
+            keys_to_remove = []
+            for key, (_, expiry_time) in self.cache.items():
+                if current_time >= expiry_time:
+                    keys_to_remove.append(key)
+            
+            for key in keys_to_remove:
+                del self.cache[key]
+                removed_count += 1
+        
+        if removed_count > 0:
+            logger.debug(f"Cleaned up {removed_count} expired cache entries")
+        
+        return removed_count
+    
+    def get_stats(self) -> Dict[str, Any]:
+        """Get cache statistics."""
+        with self.lock:
+            total_requests = self.hit_count + self.miss_count
+            hit_rate = (self.hit_count / total_requests * 100) if total_requests > 0 else 0
+            
+            return {
+                "entries": len(self.cache),
+                "hits": self.hit_count,
+                "misses": self.miss_count,
+                "hit_rate": f"{hit_rate:.1f}%",
+                "total_requests": total_requests
+            }
+
+# Global cache instance
+_cache = ThingsCache()
+
+def cached(ttl: Optional[int] = None, invalidate_on: Optional[list] = None):
+    """
+    Decorator for caching function results.
+    
+    Args:
+        ttl: Time-to-live for cached results in seconds
+        invalidate_on: List of operation names that should invalidate this cache
+        
+    Example:
+        @cached(ttl=60)
+        def get_projects():
+            return things.projects()
+    """
+    def decorator(func: Callable) -> Callable:
+        @wraps(func)
+        def wrapper(*args, **kwargs):
+            # Create operation name from function
+            operation = func.__name__
+            
+            # Check cache first
+            cached_value = _cache.get(operation, **kwargs)
+            if cached_value is not None:
+                return cached_value
+            
+            # Call the actual function
+            result = func(*args, **kwargs)
+            
+            # Cache the result
+            _cache.set(operation, result, ttl=ttl, **kwargs)
+            
+            return result
+        
+        # Store invalidation info
+        if invalidate_on:
+            wrapper._invalidate_on = invalidate_on
+        
+        return wrapper
+    return decorator
+
+def invalidate_caches_for(operations: list) -> None:
+    """
+    Invalidate caches for specific operations.
+    
+    This is useful when data is modified and related caches need to be cleared.
+    
+    Args:
+        operations: List of operation names to invalidate
+    """
+    for operation in operations:
+        _cache.invalidate(operation)
+
+def get_cache_stats() -> Dict[str, Any]:
+    """Get cache statistics."""
+    return _cache.get_stats()
+
+def clear_cache() -> None:
+    """Clear all cached data."""
+    _cache.invalidate()
+
+# TTL configurations for different types of data
+CACHE_TTL = {
+    "inbox": 30,          # 30 seconds - changes frequently
+    "today": 30,          # 30 seconds - changes frequently  
+    "upcoming": 60,       # 1 minute
+    "anytime": 300,       # 5 minutes
+    "someday": 300,       # 5 minutes
+    "projects": 300,      # 5 minutes
+    "areas": 600,         # 10 minutes - rarely changes
+    "tags": 600,          # 10 minutes - rarely changes
+    "logbook": 300,       # 5 minutes
+    "trash": 300,         # 5 minutes
+}
+
+# Auto-cleanup task
+def start_cache_cleanup_task(interval: int = 300):
+    """Start a background task to clean up expired cache entries."""
+    import threading
+    
+    def cleanup_task():
+        while True:
+            time.sleep(interval)
+            _cache.cleanup_expired()
+    
+    thread = threading.Thread(target=cleanup_task, daemon=True)
+    thread.start()
+    logger.info(f"Started cache cleanup task with {interval}s interval")
+
+# Start cleanup task when module is imported
+start_cache_cleanup_task()

things_mcp/config.py

@@ -0,0 +1,120 @@
+"""
+Configuration module for Things MCP.
+Stores settings and user-specific configuration values.
+"""
+import os
+import json
+import logging
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+# Default configuration values
+DEFAULT_CONFIG = {
+    "things_auth_token": "",  # Empty by default, must be set by user
+    "retry_attempts": 3,
+    "retry_delay": 1.0
+}
+
+# Path to the configuration file
+CONFIG_DIR = Path.home() / ".things-mcp"
+CONFIG_FILE = CONFIG_DIR / "config.json"
+
+# Global configuration dictionary
+_config = None
+
+def load_config():
+    """Load configuration from file, create with defaults if it doesn't exist."""
+    global _config
+    
+    # Create config directory if it doesn't exist
+    if not CONFIG_DIR.exists():
+        try:
+            CONFIG_DIR.mkdir(parents=True)
+            logger.info(f"Created configuration directory: {CONFIG_DIR}")
+        except Exception as e:
+            logger.error(f"Failed to create config directory: {e}")
+            return DEFAULT_CONFIG
+    
+    # Check if config file exists
+    if not CONFIG_FILE.exists():
+        # Create default config file
+        try:
+            with open(CONFIG_FILE, 'w') as f:
+                json.dump(DEFAULT_CONFIG, f, indent=2)
+            logger.info(f"Created default configuration file: {CONFIG_FILE}")
+            _config = DEFAULT_CONFIG.copy()
+        except Exception as e:
+            logger.error(f"Failed to create config file: {e}")
+            _config = DEFAULT_CONFIG.copy()
+    else:
+        # Load existing config
+        try:
+            with open(CONFIG_FILE, 'r') as f:
+                loaded_config = json.load(f)
+                
+                # Ensure all required keys are present
+                _config = DEFAULT_CONFIG.copy()
+                _config.update(loaded_config)
+                
+            logger.info(f"Loaded configuration from: {CONFIG_FILE}")
+        except Exception as e:
+            logger.error(f"Failed to load config file: {e}")
+            _config = DEFAULT_CONFIG.copy()
+    
+    return _config
+
+def save_config():
+    """Save current configuration to file."""
+    if _config is None:
+        logger.error("Cannot save config: No configuration loaded")
+        return False
+    
+    try:
+        with open(CONFIG_FILE, 'w') as f:
+            json.dump(_config, f, indent=2)
+        logger.info(f"Saved configuration to: {CONFIG_FILE}")
+        return True
+    except Exception as e:
+        logger.error(f"Failed to save config: {e}")
+        return False
+
+def get_config():
+    """Get the current configuration, loading it if necessary."""
+    global _config
+    if _config is None:
+        _config = load_config()
+    return _config
+
+def set_config_value(key, value):
+    """Set a configuration value and save to file."""
+    config = get_config()
+    config[key] = value
+    return save_config()
+
+def get_config_value(key, default=None):
+    """Get a configuration value, return default if not found."""
+    config = get_config()
+    return config.get(key, default)
+
+def get_things_auth_token():
+    """Get the Things authentication token.
+    
+    First checks environment variable THINGS_AUTH_TOKEN, 
+    then falls back to config file.
+    """
+    # Check environment variable first
+    token = os.environ.get('THINGS_AUTH_TOKEN')
+    if token:
+        logger.debug("Using Things auth token from environment variable")
+        return token
+    
+    # Fall back to config file
+    return get_config_value("things_auth_token", "")
+
+def set_things_auth_token(token):
+    """Set the Things authentication token."""
+    return set_config_value("things_auth_token", token)
+
+# Initialize configuration on module import
+load_config()