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

things_mcp/url_scheme.py

@@ -0,0 +1,318 @@
+import urllib.parse
+import webbrowser
+import things
+import subprocess
+import platform
+import random
+import time
+import logging
+import json
+from typing import Optional, Dict, Any, Union, Callable
+from .utils import app_state, circuit_breaker, dead_letter_queue, rate_limiter, is_things_running
+
+logger = logging.getLogger(__name__)
+        
+def launch_things() -> bool:
+    """Launch Things app if not already running.
+    
+    Returns:
+        bool: True if successful, False otherwise
+    """
+    try:
+        if is_things_running():
+            return True
+            
+        result = subprocess.run(
+            ['open', '-a', 'Things3'],
+            capture_output=True,
+            text=True,
+            check=False
+        )
+        
+        # Give Things time to launch
+        time.sleep(2)
+        
+        return is_things_running()
+    except Exception as e:
+        logger.error(f"Error launching Things: {str(e)}")
+        return False
+
+def execute_url(url: str) -> bool:
+    """Execute a Things URL by opening it in the default browser.
+    Returns True if successful, False otherwise.
+    """
+    # Ensure any + signs in the URL are replaced with %20
+    url = url.replace("+", "%20")
+    
+    # Log the URL for debugging
+    logger.debug(f"Executing URL: {url}")
+    
+    # Apply rate limiting
+    rate_limiter.wait_if_needed()
+    
+    # Check if circuit breaker allows the operation
+    if not circuit_breaker.allow_operation():
+        logger.warning("Circuit breaker is open, blocking operation")
+        return False
+    
+    try:
+        # Check if Things is running, attempt to launch if not
+        if not is_things_running():
+            logger.info("Things is not running, attempting to launch")
+            if not launch_things():
+                logger.error("Failed to launch Things")
+                circuit_breaker.record_failure()
+                return False
+        
+        # Execute the URL
+        result = webbrowser.open(url)
+        
+        if not result:
+            circuit_breaker.record_failure()
+            logger.error(f"Failed to open URL: {url}")
+            return False
+        
+        # Add a small delay to allow Things time to process the command
+        # Add jitter to prevent thundering herd problem
+        delay = 0.5 + random.uniform(0, 0.2)  # 0.5-0.7 seconds
+        time.sleep(delay)
+        
+        circuit_breaker.record_success()
+        return True
+    except Exception as e:
+        logger.error(f"Failed to execute URL: {url}, Error: {str(e)}")
+        circuit_breaker.record_failure()
+        return False
+
+
+def execute_xcallback_url(action: str, params: Dict[str, Any]) -> bool:
+    """Execute a Things X-Callback-URL.
+    
+    Args:
+        action: The X-Callback action to perform
+        params: Parameters for the action
+        
+    Returns:
+        bool: True if successful, False otherwise
+    """
+    # The correct format for Things URLs (no 'x-callback-url/' prefix)
+    base_url = "things:///"
+    
+    # Add callback parameters, but only if we need them
+    # For now, avoid using callbacks since we don't have a handler for them
+    callback_params = params.copy()
+    
+    # Don't add callback URLs - this avoids the "no application set to open URL" error
+    # If we need callbacks later, we'd need to register a URL handler for our app
+    
+    # Construct URL - action is part of the path (not a separate query parameter)
+    url = f"{base_url}{action}?{urllib.parse.urlencode(callback_params)}"
+    
+    # Log the URL for debugging
+    logger.debug(f"Executing URL: {url}")
+    
+    return execute_url(url)
+
+def construct_url(command: str, params: Dict[str, Any]) -> str:
+    """Construct a Things URL from command and parameters."""
+    # Pre-process all string parameters to replace any + signs with spaces
+    cleaned_params = {}
+    for key, value in params.items():
+        if isinstance(value, str):
+            # Replace any + signs with spaces in the original input
+            cleaned_params[key] = value.replace("+", " ")
+        else:
+            cleaned_params[key] = value
+    
+    # Use the cleaned params from now on
+    params = cleaned_params
+    
+    # Start with base URL
+    url = f"things:///{command}"
+    
+    # Get authentication token if needed - applies to all commands to ensure reliability
+    try:
+        # Import here to avoid circular imports
+        from . import config
+        
+        # Get token from config system
+        token = config.get_things_auth_token()
+        
+        if token:
+            # Add token to all params for consistent behavior
+            params['auth-token'] = token
+            logger.debug(f"Auth token from config used for {command} operation")
+        else:
+            logger.warning(f"No Things auth token found in config. URL may not work without a token.")
+            # Note: We continue without a token, which may cause the operation to fail
+    except Exception as e:
+        logger.error(f"Error getting auth token: {str(e)}")
+        # Continue without token - the operation may fail
+    
+    # Disable JSON API for now as it's causing formatting issues
+    # JSON API is currently experimental and unreliable
+    # We'll use the standard URL scheme instead which is more reliable
+    use_json_api = False
+    
+    if False and command in ['add'] and use_json_api:
+        # This code is disabled but kept for reference
+        logger.info("JSON API is currently disabled due to formatting issues")
+        pass
+    
+    # Standard URL scheme encoding
+    if params:
+        encoded_params = []
+        for key, value in params.items():
+            if value is None:
+                continue
+            # Handle boolean values
+            if isinstance(value, bool):
+                value = str(value).lower()
+            # Handle lists (for tags, checklist items etc)
+            elif isinstance(value, list) and key == 'tags':
+                # Important: Tags are sensitive to formatting in Things URL scheme
+                # Based on testing, using a simple comma-separated list without spaces works best
+                encoded_tags = []
+                for tag in value:
+                    # Ensure tag is properly encoded as string
+                    tag_str = str(tag).strip()
+                    if tag_str:  # Only add non-empty tags
+                        encoded_tags.append(tag_str)
+                
+                # Only include non-empty tag lists
+                if encoded_tags:
+                    # Join with commas - Things expects comma-separated tags without spaces between commas
+                    # Use a simple comma with no spacing for maximum compatibility
+                    value = ','.join(encoded_tags)
+                else:
+                    # If no valid tags, don't include this parameter
+                    continue
+            # Handle other lists
+            elif isinstance(value, list):
+                value = ','.join(str(v) for v in value)
+            
+            # Ensure proper encoding of the value - use quote_plus to handle spaces correctly
+            # Then replace + with %20 to ensure Things handles spaces correctly
+            encoded_value = urllib.parse.quote(str(value), safe='')
+            # Replace + with %20 for better compatibility with Things
+            encoded_value = encoded_value.replace('+', '%20')
+            encoded_params.append(f"{key}={encoded_value}")
+        
+        url += "?" + "&".join(encoded_params)
+    
+    return url
+
+
+def should_use_json_api() -> bool:
+    """Determine if the JSON API should be used based on Things version."""
+    from .utils import detect_things_version
+    
+    version = detect_things_version()
+    if not version:
+        # Default to using JSON API if version can't be determined
+        return True
+    
+    try:
+        # Parse version string (e.g., '3.15.4')
+        major, minor, _ = map(int, version.split('.'))
+        
+        # JSON API is available in Things 3.4+
+        return major > 3 or (major == 3 and minor >= 4)
+    except Exception:
+        # Default to standard URL scheme if version parsing fails
+        return False
+
+def add_todo(title: str, notes: Optional[str] = None, when: Optional[str] = None,
+             deadline: Optional[str] = None, tags: Optional[list[str]] = None,
+             checklist_items: Optional[list[str]] = None, list_id: Optional[str] = None,
+             list_title: Optional[str] = None, heading: Optional[str] = None,
+             completed: Optional[bool] = None) -> str:
+    """Construct URL to add a new todo."""
+    params = {
+        'title': title,
+        'notes': notes,
+        'when': when,
+        'deadline': deadline,
+        'checklist-items': '\n'.join(checklist_items) if checklist_items else None,
+        'list-id': list_id,
+        'list': list_title,
+        'heading': heading,
+        'completed': completed
+    }
+    
+    # Handle tags separately since they need to be comma-separated
+    if tags:
+        params['tags'] = ','.join(tags)
+    return construct_url('add', {k: v for k, v in params.items() if v is not None})
+
+def add_project(title: str, notes: Optional[str] = None, when: Optional[str] = None,
+                deadline: Optional[str] = None, tags: Optional[list[str]] = None,
+                area_id: Optional[str] = None, area_title: Optional[str] = None,
+                todos: Optional[list[str]] = None) -> str:
+    """Construct URL to add a new project."""
+    params = {
+        'title': title,
+        'notes': notes,
+        'when': when,
+        'deadline': deadline,
+        'area-id': area_id,
+        'area': area_title,
+        # Change todos to be newline separated
+        'to-dos': '\n'.join(todos) if todos else None
+    }
+    
+    # Handle tags separately since they need to be comma-separated
+    if tags:
+        params['tags'] = ','.join(tags)
+        
+    return construct_url('add-project', {k: v for k, v in params.items() if v is not None})
+
+def update_todo(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) -> str:
+    """Construct URL to update an existing todo."""
+    params = {
+        'id': id,
+        'title': title,
+        'notes': notes,
+        'when': when,
+        'deadline': deadline,
+        'tags': tags,
+        'add-tags': add_tags,  # Support for adding tags without replacing existing ones
+        'checklist-items': '\n'.join(checklist_items) if checklist_items else None,
+        'completed': completed,
+        'canceled': canceled
+    }
+    return construct_url('update', {k: v for k, v in params.items() if v is not None})
+
+def update_project(id: str, title: Optional[str] = None, notes: Optional[str] = None,
+                   when: Optional[str] = None, deadline: Optional[str] = None,
+                   tags: Optional[list[str]] = None, completed: Optional[bool] = None,
+                   canceled: Optional[bool] = None) -> str:
+    """Construct URL to update an existing project."""
+    params = {
+        'id': id,
+        'title': title,
+        'notes': notes,
+        'when': when,
+        'deadline': deadline,
+        'tags': tags,
+        'completed': completed,
+        'canceled': canceled
+    }
+    return construct_url('update-project', {k: v for k, v in params.items() if v is not None})
+
+def show(id: str, query: Optional[str] = None, filter_tags: Optional[list[str]] = None) -> str:
+    """Construct URL to show a specific item or list."""
+    params = {
+        'id': id,
+        'query': query,
+        'filter': filter_tags
+    }
+    return construct_url('show', {k: v for k, v in params.items() if v is not None})
+
+def search(query: str) -> str:
+    """Construct URL to perform a search."""
+    return construct_url('search', {'query': query})

things_mcp/utils.py

@@ -0,0 +1,360 @@
+"""
+Utility classes and functions for enhancing Things MCP reliability.
+"""
+import json
+import time
+import logging
+import os
+import platform
+import subprocess
+import urllib.parse
+import mcp.types as types
+from typing import Dict, Any, Optional, Callable, List, Union
+
+logger = logging.getLogger(__name__)
+
+
+def is_things_running() -> bool:
+    """Check if Things app is running.
+    
+    Returns:
+        bool: True if Things is running, False otherwise
+    """
+    try:
+        if platform.system() != 'Darwin':
+            logger.warning("Things availability check only works on macOS")
+            return True
+            
+        result = subprocess.run(
+            ['osascript', '-e', 'tell application "System Events" to (name of processes) contains "Things3"'],
+            capture_output=True,
+            text=True,
+            check=False
+        )
+        is_running = result.stdout.strip().lower() == 'true'
+        
+        # If Things is running, also check if it's responsive
+        if is_running:
+            # Simple ping to see if Things responds
+            ping_result = subprocess.run(
+                ['osascript', '-e', 'tell application "Things3" to return name'],
+                capture_output=True,
+                text=True,
+                check=False,
+                timeout=2  # 2 second timeout
+            )
+            is_responsive = ping_result.returncode == 0
+            
+            if not is_responsive:
+                logger.warning("Things is running but not responsive")
+                return False
+                
+        return is_running
+    except subprocess.TimeoutExpired:
+        logger.warning("Things app check timed out")
+        return False
+    except Exception as e:
+        logger.error(f"Error checking if Things is running: {str(e)}")
+        return False
+
+class ThingsAppState:
+    """Track and manage Things app state"""
+    
+    def __init__(self):
+        self.is_available = False
+        self.last_check_time = 0
+        self.check_interval = 5  # seconds
+        self.update_app_state()
+    
+    def update_app_state(self):
+        """Update app availability state"""
+        current_time = time.time()
+        if current_time - self.last_check_time > self.check_interval:
+            self.is_available = is_things_running()
+            self.last_check_time = current_time
+        return self.is_available
+    
+    def wait_for_app_availability(self, timeout=10):
+        """Wait for app to become available within timeout"""
+        start_time = time.time()
+        while time.time() - start_time < timeout:
+            if self.update_app_state():
+                return True
+            time.sleep(0.5)
+        return False
+
+
+def validate_tool_registration(tools: list[types.Tool]) -> bool:
+    """
+    Validate that all required Things MCP tools are properly registered.
+    
+    Args:
+        tools: List of registered tools
+        
+    Returns:
+        bool: True if all required tools are registered, False otherwise
+    """
+    required_tool_names = [
+        "get-inbox", "get-today", "get-upcoming", "get-anytime",
+        "get-someday", "get-logbook", "get-trash", "get-todos",
+        "get-projects", "get-areas", "get-tags", "get-tagged-items",
+        "search-todos", "search-advanced", "get-recent", "add-todo",
+        "search-items", "add-project", "update-todo", "update-project", "show-item"
+    ]
+    
+    registered_tool_names = [tool.name for tool in tools]
+    
+    # Check if all required tools are registered
+    missing_tools = [name for name in required_tool_names if name not in registered_tool_names]
+    
+    if missing_tools:
+        logger.error(f"Missing required tool registrations: {missing_tools}")
+        return False
+        
+    # Check if all registered tools have proper descriptions and parameters
+    for tool in tools:
+        if not tool.description or len(tool.description) < 10:
+            logger.warning(f"Tool '{tool.name}' has an insufficient description")
+        
+        # Basic parameter validation could be added here
+        # This would depend on your tool schema requirements
+    
+    return True
+
+
+class CircuitBreaker:
+    """Circuit breaker to prevent repeated failed attempts"""
+    
+    # Circuit states
+    CLOSED = "closed"  # Normal operation
+    OPEN = "open"      # Not allowing operations
+    HALF_OPEN = "half-open"  # Testing if system has recovered
+    
+    def __init__(self, failure_threshold=5, recovery_timeout=60):
+        self.state = self.CLOSED
+        self.failure_count = 0
+        self.failure_threshold = failure_threshold
+        self.recovery_timeout = recovery_timeout
+        self.last_failure_time = 0
+    
+    def record_failure(self):
+        """Record a failure and potentially open the circuit"""
+        self.failure_count += 1
+        self.last_failure_time = time.time()
+        
+        if self.failure_count >= self.failure_threshold:
+            self.state = self.OPEN
+            logger.warning(f"Circuit breaker opened after {self.failure_count} failures")
+    
+    def record_success(self):
+        """Record a success and reset the circuit if in half-open state"""
+        if self.state == self.HALF_OPEN:
+            self.state = self.CLOSED
+            self.failure_count = 0
+            logger.info("Circuit breaker closed after successful operation")
+        elif self.state == self.CLOSED:
+            self.failure_count = 0
+    
+    def allow_operation(self):
+        """Check if operation should be allowed"""
+        if self.state == self.CLOSED:
+            return True
+        
+        if self.state == self.OPEN:
+            # Check if recovery timeout has elapsed
+            if time.time() - self.last_failure_time > self.recovery_timeout:
+                self.state = self.HALF_OPEN
+                logger.info("Circuit breaker half-open, testing system recovery")
+                return True
+            return False
+        
+        # Half-open state allows a single test operation
+        return True
+
+
+class DeadLetterQueue:
+    """Store persistently failed operations for manual review"""
+    
+    def __init__(self, dlq_file="things_dlq.json"):
+        self.dlq_file = dlq_file
+        self.queue = self._load_queue()
+        
+    def _load_queue(self):
+        """Load persisted queue"""
+        try:
+            if os.path.exists(self.dlq_file):
+                with open(self.dlq_file, 'r') as f:
+                    return json.load(f)
+            return []
+        except Exception as e:
+            logger.error(f"Error loading DLQ: {str(e)}")
+            return []
+    
+    def _save_queue(self):
+        """Persist queue to disk"""
+        try:
+            with open(self.dlq_file, 'w') as f:
+                json.dump(self.queue, f)
+        except Exception as e:
+            logger.error(f"Error saving DLQ: {str(e)}")
+    
+    def add_failed_operation(self, operation, params, error, attempts=1):
+        """Add failed operation to dead letter queue"""
+        entry = {
+            "operation": operation,
+            "params": params,
+            "error": str(error),
+            "attempts": attempts,
+            "timestamp": time.time(),
+            "added_at": time.strftime("%Y-%m-%d %H:%M:%S")
+        }
+        
+        self.queue.append(entry)
+        self._save_queue()
+        logger.warning(f"Added to DLQ: {operation} with error: {str(error)}")
+    
+    def retry_all(self):
+        """Attempt to retry all operations in the DLQ"""
+        if not self.queue:
+            return {"success": True, "retried": 0, "failed": 0}
+        
+        from .url_scheme import construct_url, execute_url
+        
+        success_count = 0
+        failure_count = 0
+        remaining_queue = []
+        
+        for entry in self.queue:
+            try:
+                url = construct_url(entry["operation"], entry["params"])
+                result = retry_operation(lambda: execute_url(url))
+                
+                if result:
+                    success_count += 1
+                else:
+                    entry["attempts"] += 1
+                    remaining_queue.append(entry)
+                    failure_count += 1
+            except Exception:
+                entry["attempts"] += 1
+                remaining_queue.append(entry)
+                failure_count += 1
+        
+        self.queue = remaining_queue
+        self._save_queue()
+        
+        return {
+            "success": failure_count == 0,
+            "retried": success_count + failure_count,
+            "failed": failure_count
+        }
+
+
+class RateLimiter:
+    """Intelligent rate limiter for Things operations"""
+    
+    def __init__(self, operations_per_minute=30):
+        self.operations_per_minute = operations_per_minute
+        self.operation_interval = 60 / operations_per_minute
+        self.last_operation_time = 0
+    
+    def wait_if_needed(self):
+        """Wait if necessary to maintain rate limit"""
+        current_time = time.time()
+        time_since_last = current_time - self.last_operation_time
+        
+        if time_since_last < self.operation_interval:
+            # Need to wait
+            wait_time = self.operation_interval - time_since_last
+            time.sleep(wait_time)
+        
+        self.last_operation_time = time.time()
+    
+    def __call__(self, func):
+        """Decorator to rate limit a function"""
+        def wrapper(*args, **kwargs):
+            self.wait_if_needed()
+            return func(*args, **kwargs)
+        return wrapper
+
+
+def get_auth_token() -> Optional[str]:
+    """Get the Things authentication token from various possible sources.
+    
+    The function tries to get the token from:
+    1. Environment variable THINGS_AUTH_TOKEN
+    2. Local config file
+    3. Hardcoded fallback value
+    
+    Returns:
+        str: Authentication token if found, None otherwise
+    """
+    # Try environment variable first
+    token = os.environ.get('THINGS_AUTH_TOKEN')
+    if token:
+        logger.info("Using Things authentication token from environment variable")
+        return token
+    
+    # Try local config file
+    try:
+        config_path = os.path.expanduser("~/.things_config.json")
+        if os.path.exists(config_path):
+            with open(config_path, 'r') as f:
+                config = json.load(f)
+                if 'auth_token' in config and config['auth_token']:
+                    logger.info("Using Things authentication token from config file")
+                    return config['auth_token']
+    except Exception as e:
+        logger.warning(f"Failed to read auth token from config file: {str(e)}")
+    
+    # No token found from dynamic sources
+    logger.warning("No Things authentication token found in environment or config")
+    return None
+
+
+def detect_things_version():
+    """Detect installed Things version"""
+    try:
+        # Use AppleScript to get Things version
+        script = 'tell application "Things3" to return version'
+        result = subprocess.run(
+            ['osascript', '-e', script],
+            capture_output=True,
+            text=True,
+            check=False
+        )
+        
+        if result.returncode == 0 and result.stdout.strip():
+            return result.stdout.strip()
+    except Exception as e:
+        logger.error(f"Error detecting Things version: {str(e)}")
+    
+    return None
+
+
+def validate_tool_registration(tool_list):
+    """Validate that all tools are properly registered"""
+    required_tools = [
+        "get-inbox", "get-today", "get-upcoming", "get-anytime",
+        "get-someday", "get-logbook", "get-trash", "get-todos",
+        "get-projects", "get-areas", "get-tags", "get-tagged-items",
+        "search-todos", "search-advanced", "get-recent", "add-todo",
+        "add-project", "update-todo", "update-project", "show-item"
+    ]
+    
+    tool_names = [t.name for t in tool_list]
+    missing_tools = [tool for tool in required_tools if tool not in tool_names]
+    
+    if missing_tools:
+        logger.error(f"Missing tool registrations: {missing_tools}")
+        return False
+    
+    logger.info(f"All {len(tool_list)} tools are properly registered")
+    return True
+
+
+# Create global instances
+app_state = ThingsAppState()
+circuit_breaker = CircuitBreaker()
+dead_letter_queue = DeadLetterQueue()
+rate_limiter = RateLimiter()