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

things_mcp/simple_url_scheme.py

@@ -0,0 +1,230 @@
+#!/usr/bin/env python3
+"""
+Simplified URL scheme implementation for Things.
+Based on https://culturedcode.com/things/support/articles/2803573/
+"""
+import urllib.parse
+import webbrowser
+import subprocess
+import time
+import logging
+from typing import Optional, Dict, Any, List
+
+logger = logging.getLogger(__name__)
+
+def launch_things() -> bool:
+    """Launch Things app if not already running."""
+    try:
+        # Check if running
+        result = subprocess.run(
+            ['osascript', '-e', 'tell application "System Events" to (name of processes) contains "Things3"'],
+            capture_output=True,
+            text=True,
+            check=False
+        )
+        
+        if result.stdout.strip().lower() == 'true':
+            return True
+            
+        # Launch Things
+        subprocess.run(['open', '-a', 'Things3'], capture_output=True, check=False)
+        time.sleep(2)  # Give it time to start
+        return True
+    except Exception as e:
+        logger.error(f"Error launching Things: {str(e)}")
+        return False
+
+def execute_url(url: str) -> bool:
+    """Execute a Things URL."""
+    try:
+        logger.debug(f"Executing URL: {url}")
+        
+        # Ensure Things is running
+        launch_things()
+        
+        # Execute the URL
+        result = webbrowser.open(url)
+        
+        # Small delay to let Things process
+        time.sleep(0.5)
+        
+        return result
+    except Exception as e:
+        logger.error(f"Failed to execute URL: {str(e)}")
+        return False
+
+def construct_url(command: str, params: Dict[str, Any]) -> str:
+    """Construct a Things URL from command and parameters."""
+    # Start with base URL
+    url = f"things:///{command}"
+    
+    # Get authentication token if available
+    try:
+        from . import config
+        token = config.get_things_auth_token()
+        if token:
+            params['auth-token'] = token
+            logger.debug(f"Added authentication token to {command} URL")
+        else:
+            logger.warning(f"No authentication token configured for {command} URL")
+    except Exception as e:
+        logger.error(f"Failed to get authentication token: {str(e)}")
+        # Try environment variable as fallback
+        import os
+        token = os.environ.get('THINGS_AUTH_TOKEN')
+        if token:
+            params['auth-token'] = token
+            logger.debug(f"Using authentication token from environment variable")
+    
+    # Filter out None values
+    params = {k: v for k, v in params.items() if v is not None}
+    
+    if params:
+        encoded_params = []
+        for key, value in params.items():
+            if isinstance(value, bool):
+                value = str(value).lower()
+            elif isinstance(value, list):
+                if key == 'tags':
+                    # Tags should be comma-separated
+                    value = ','.join(str(v) for v in value)
+                elif key == 'checklist-items':
+                    # Checklist items should be newline-separated
+                    value = '\n'.join(str(v) for v in value)
+                else:
+                    value = ','.join(str(v) for v in value)
+            
+            # URL encode the value
+            encoded_value = urllib.parse.quote(str(value), safe='')
+            encoded_params.append(f"{key}={encoded_value}")
+        
+        url += "?" + "&".join(encoded_params)
+    
+    return url
+
+# URL scheme functions based on Things documentation
+
+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: Optional[str] = None,  # Project/Area name
+    heading: Optional[str] = None,
+    completed: Optional[bool] = None
+) -> bool:
+    """Add a new todo using Things URL scheme."""
+    params = {
+        'title': title,
+        'notes': notes,
+        'when': when,
+        'deadline': deadline,
+        'tags': tags,
+        'checklist-items': checklist_items,
+        'list-id': list_id,
+        'list': list,  # This is the project/area name
+        'heading': heading,
+        'completed': completed
+    }
+    
+    url = construct_url('add', params)
+    return execute_url(url)
+
+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: Optional[str] = None,  # Area name
+    todos: Optional[List[str]] = None
+) -> bool:
+    """Add a new project using Things URL scheme."""
+    params = {
+        'title': title,
+        'notes': notes,
+        'when': when,
+        'deadline': deadline,
+        'tags': tags,
+        'area-id': area_id,
+        'area': area,
+        'to-dos': todos  # List of todo titles
+    }
+    
+    url = construct_url('add-project', params)
+    return execute_url(url)
+
+def update_todo(
+    id: str,
+    title: Optional[str] = None,
+    notes: Optional[str] = None,
+    when: Optional[str] = None,
+    deadline: Optional[str] = None,
+    tags: Optional[List[str]] = None,
+    add_tags: Optional[List[str]] = None,
+    completed: Optional[bool] = None,
+    canceled: Optional[bool] = None
+) -> bool:
+    """Update an existing todo."""
+    params = {
+        'id': id,
+        'title': title,
+        'notes': notes,
+        'when': when,
+        'deadline': deadline,
+        'tags': tags,
+        'add-tags': add_tags,
+        'completed': completed,
+        'canceled': canceled
+    }
+    
+    url = construct_url('update', params)
+    return execute_url(url)
+
+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
+) -> bool:
+    """Update an existing project."""
+    params = {
+        'id': id,
+        'title': title,
+        'notes': notes,
+        'when': when,
+        'deadline': deadline,
+        'tags': tags,
+        'completed': completed,
+        'canceled': canceled
+    }
+    
+    url = construct_url('update-project', params)
+    return execute_url(url)
+
+def show(
+    id: str,
+    query: Optional[str] = None,
+    filter: Optional[List[str]] = None
+) -> bool:
+    """Show a specific item or list in Things."""
+    params = {
+        'id': id,
+        'query': query,
+        'filter': filter
+    }
+    
+    url = construct_url('show', params)
+    return execute_url(url)
+
+def search(query: str) -> bool:
+    """Search for items in Things."""
+    return show(id='search', query=query)

things_mcp/tag_handler.py

@@ -0,0 +1,111 @@
+#!/usr/bin/env python3
+"""
+Tag handler for Things MCP.
+Ensures tags exist before applying them.
+"""
+import subprocess
+import logging
+from typing import List, Optional
+
+logger = logging.getLogger(__name__)
+
+def ensure_tags_exist(tags: List[str]) -> bool:
+    """
+    Ensure all tags exist in Things before using them.
+    Creates missing tags using AppleScript.
+    
+    Args:
+        tags: List of tag names to ensure exist
+        
+    Returns:
+        bool: True if all tags exist or were created successfully
+    """
+    if not tags:
+        return True
+        
+    try:
+        # Build AppleScript to check and create tags
+        script_lines = ['tell application "Things3"']
+        
+        for tag in tags:
+            # Escape quotes in tag name
+            escaped_tag = tag.replace('"', '\\"')
+            
+            # Check if tag exists, create if not
+            script_lines.extend([
+                f'  set tagName to "{escaped_tag}"',
+                '  set tagExists to false',
+                '  repeat with t in tags',
+                '    if name of t is tagName then',
+                '      set tagExists to true',
+                '      exit repeat',
+                '    end if',
+                '  end repeat',
+                '  if not tagExists then',
+                '    try',
+                '      make new tag with properties {name:tagName}',
+                f'      log "Created tag: " & tagName',
+                '    on error',
+                f'      log "Failed to create tag: " & tagName',
+                '    end try',
+                '  end if'
+            ])
+        
+        script_lines.append('end tell')
+        script = '\n'.join(script_lines)
+        
+        # Execute the AppleScript
+        result = subprocess.run(
+            ['osascript', '-e', script],
+            capture_output=True,
+            text=True,
+            timeout=10
+        )
+        
+        if result.returncode != 0:
+            logger.error(f"Failed to ensure tags exist: {result.stderr}")
+            return False
+            
+        logger.info(f"Ensured tags exist: {', '.join(tags)}")
+        return True
+        
+    except subprocess.TimeoutExpired:
+        logger.error("Timeout while ensuring tags exist")
+        return False
+    except Exception as e:
+        logger.error(f"Error ensuring tags exist: {str(e)}")
+        return False
+
+def get_existing_tags() -> List[str]:
+    """
+    Get list of all existing tags in Things.
+    
+    Returns:
+        List[str]: List of tag names
+    """
+    try:
+        script = '''tell application "Things3"
+            set tagList to {}
+            repeat with t in tags
+                set end of tagList to name of t
+            end repeat
+            return tagList
+        end tell'''
+        
+        result = subprocess.run(
+            ['osascript', '-e', script],
+            capture_output=True,
+            text=True,
+            timeout=5
+        )
+        
+        if result.returncode == 0 and result.stdout:
+            # Parse the output (comma-separated list)
+            tags = [tag.strip() for tag in result.stdout.strip().split(',')]
+            return tags
+        
+        return []
+        
+    except Exception as e:
+        logger.error(f"Error getting existing tags: {str(e)}")
+        return []

things_mcp/things_server.py

@@ -0,0 +1,106 @@
+from typing import Any, List, Optional, Dict
+import logging
+import asyncio
+import sys
+import re
+import traceback
+from mcp.server.models import InitializationOptions
+import mcp.types as types
+from mcp.server import NotificationOptions, Server
+import mcp.server.stdio
+
+# Import our direct MCP tool definitions for Windsurf compatibility
+from mcp_tools import get_mcp_tools_list
+from handlers import handle_tool_call
+from utils import validate_tool_registration, app_state
+import url_scheme
+
+# Configure logging
+logging.basicConfig(level=logging.DEBUG)
+logger = logging.getLogger(__name__)
+
+server = Server("things")
+
+@server.list_tools()
+async def handle_list_tools() -> list[types.Tool]:
+    """List available tools for Things integration with Windsurf compatibility."""
+    return get_mcp_tools_list()
+
+@server.call_tool()
+async def handle_call_tool(
+    name: str, arguments: dict | None
+) -> list[types.TextContent | types.ImageContent | types.EmbeddedResource]:
+    """Handle tool execution requests with Windsurf compatibility."""
+    try:
+        # Handle both prefixed and non-prefixed tool names consistently
+        # If name has mcp2_ prefix, remove it for handler compatibility
+        # If name doesn't have prefix, use it directly
+        
+        original_name = name
+        base_name = name
+        
+        # Check if the name has the 'mcp2_' prefix and remove it if present
+        if name.startswith("mcp2_"):
+            base_name = name[5:]  # Remove the 'mcp2_' prefix
+            logger.info(f"Received prefixed tool call: {name} -> mapping to {base_name}")
+        else:
+            # No prefix, check if the name is one of our supported tools
+            # This allows both prefixed and direct calls to work
+            logger.info(f"Received non-prefixed tool call: {name}")
+        
+        # Log the incoming arguments for debugging
+        argument_summary = str(arguments)[:100] + "..." if arguments and len(str(arguments)) > 100 else str(arguments)
+        logger.info(f"MCP tool call received: {original_name} (handling as: {base_name}) with arguments: {argument_summary}")
+        
+        # Call the appropriate handler with robust error handling
+        try:
+            return await handle_tool_call(base_name, arguments)
+        except Exception as e:
+            error_message = f"Error executing tool {name}: {str(e)}"
+            logger.error(error_message)
+            logger.error(traceback.format_exc())
+            return [types.TextContent(type="text", text=f"⚠️ {error_message}")]
+    except Exception as outer_e:
+        # Catch-all to prevent server crashes
+        logger.error(f"Critical error in tool call handler: {str(outer_e)}")
+        logger.error(traceback.format_exc())
+        return [types.TextContent(type="text", text=f"⚠️ Critical error: {str(outer_e)}")]
+
+async def main():
+    # Get our MCP tools with proper naming for Windsurf
+    mcp_tools = get_mcp_tools_list()
+    
+    # Log successful registration
+    logger.info(f"Registered {len(mcp_tools)} MCP-compatible tools for Things")
+    
+    # Check if Things app is available
+    if not app_state.update_app_state():
+        logger.warning("Things app is not running at startup. MCP will attempt to launch it when needed.")
+        try:
+            # Try to launch Things
+            if url_scheme.launch_things():
+                logger.info("Successfully launched Things app")
+            else:
+                logger.error("Unable to launch Things app. Some operations may fail.")
+        except Exception as e:
+            logger.error(f"Error launching Things app: {str(e)}")
+    else:
+        logger.info("Things app is running and ready for operations")
+    
+    # Run the server using stdin/stdout streams
+    async with mcp.server.stdio.stdio_server() as (read_stream, write_stream):
+        await server.run(
+            read_stream,
+            write_stream,
+            InitializationOptions(
+                server_name="things",
+                server_version="0.1.1",  # Updated version with reliability enhancements
+                capabilities=server.get_capabilities(
+                    notification_options=NotificationOptions(),
+                    experimental_capabilities={},
+                ),
+            ),
+        )
+
+if __name__ == "__main__":
+    asyncio.run(main())