rtm_server.py

#!/usr/bin/env python3
"""
RTM MCP Server - Main server class with MCP protocol handling
"""

import json
import re
import sys
from datetime import datetime
from typing import Any, Dict, List, Optional

from rtm_client import RTMClient


class RTMMCPServer:
    """MCP Server for Remember The Milk integration."""

    def __init__(self, api_key: str, shared_secret: str):
        """
        Initialize the RTM MCP server.

        Args:
            api_key: RTM API key
            shared_secret: RTM shared secret
        """
        if not api_key or not shared_secret:
            raise ValueError("Missing RTM API credentials")

        self.rtm = RTMClient(api_key, shared_secret)
        self.list_cache = None  # Cache for list names

        # Define MCP tools
        self.tools = [
            {
                "name": "test_connection",
                "description": "Test basic connectivity to RTM API",
                "inputSchema": {"type": "object", "properties": {}, "required": []},
            },
            {
                "name": "list_all_lists",
                "description": "Get all RTM lists",
                "inputSchema": {"type": "object", "properties": {}, "required": []},
            },
            {
                "name": "create_list",
                "description": "Create a new RTM list",
                "inputSchema": {
                    "type": "object",
                    "properties": {"name": {"type": "string", "description": "Name of the new list"}},
                    "required": ["name"],
                },
            },
            {
                "name": "list_tasks",
                "description": "Get tasks from RTM with optional filtering",
                "inputSchema": {
                    "type": "object",
                    "properties": {
                        "list_id": {
                            "type": "string",
                            "description": "Filter by specific list ID (optional)",
                        },
                        "filter": {
                            "type": "string",
                            "description": "RTM search filter (e.g., 'status:incomplete', 'dueWithin:\"1 week\"')",
                        },
                        "show_ids": {"type": "boolean", "description": "Show task IDs for operations (default: false)"},
                    },
                    "required": [],
                },
            },
            {
                "name": "create_task",
                "description": "Create a new task in RTM with optional due date, priority, and tags",
                "inputSchema": {
                    "type": "object",
                    "properties": {
                        "name": {"type": "string", "description": "Task name"},
                        "list_id": {
                            "type": "string",
                            "description": "List ID to create task in (optional, uses default list if not specified)",
                        },
                        "due": {
                            "type": "string",
                            "description": 'Due date (optional, e.g., "today", "tomorrow", "next week", "June 15", "2025-06-20", "3pm", "tomorrow at 2pm")',
                        },
                        "priority": {
                            "type": "string",
                            "description": "Priority level: 1 (High), 2 (Medium), 3 (Low), or empty string (None) (optional)",
                            "enum": ["1", "2", "3", ""],
                        },
                        "tags": {"type": "string", "description": "Comma-separated list of tags to add (optional)"},
                    },
                    "required": ["name"],
                },
            },
            {
                "name": "complete_task",
                "description": "Mark a task as complete",
                "inputSchema": {
                    "type": "object",
                    "properties": {
                        "list_id": {"type": "string", "description": "List ID containing the task"},
                        "taskseries_id": {"type": "string", "description": "Task series ID"},
                        "task_id": {"type": "string", "description": "Task ID"},
                    },
                    "required": ["list_id", "taskseries_id", "task_id"],
                },
            },
            {
                "name": "delete_task",
                "description": "Permanently delete a task (stops recurrence, unlike complete_task)",
                "inputSchema": {
                    "type": "object",
                    "properties": {
                        "list_id": {"type": "string", "description": "List ID containing the task"},
                        "taskseries_id": {"type": "string", "description": "Task series ID"},
                        "task_id": {"type": "string", "description": "Task ID"},
                    },
                    "required": ["list_id", "taskseries_id", "task_id"],
                },
            },
            {
                "name": "set_task_priority",
                "description": "Set the priority of a task (1=High, 2=Medium, 3=Low, N=None)",
                "inputSchema": {
                    "type": "object",
                    "properties": {
                        "list_id": {"type": "string", "description": "List ID containing the task"},
                        "taskseries_id": {"type": "string", "description": "Task series ID"},
                        "task_id": {"type": "string", "description": "Task ID"},
                        "priority": {
                            "type": "string",
                            "description": "Priority: 1 (High), 2 (Medium), 3 (Low), or N (None)",
                            "enum": ["1", "2", "3", "N"],
                        },
                    },
                    "required": ["list_id", "taskseries_id", "task_id", "priority"],
                },
            },
            {
                "name": "add_task_tags",
                "description": "Add tags to a task",
                "inputSchema": {
                    "type": "object",
                    "properties": {
                        "list_id": {"type": "string", "description": "List ID containing the task"},
                        "taskseries_id": {"type": "string", "description": "Task series ID"},
                        "task_id": {"type": "string", "description": "Task ID"},
                        "tags": {
                            "type": "string",
                            "description": "Comma-separated list of tags to add",
                        },
                    },
                    "required": ["list_id", "taskseries_id", "task_id", "tags"],
                },
            },
            {
                "name": "remove_task_tags",
                "description": "Remove tags from a task",
                "inputSchema": {
                    "type": "object",
                    "properties": {
                        "list_id": {"type": "string", "description": "List ID containing the task"},
                        "taskseries_id": {"type": "string", "description": "Task series ID"},
                        "task_id": {"type": "string", "description": "Task ID"},
                        "tags": {
                            "type": "string",
                            "description": "Comma-separated list of tags to remove",
                        },
                    },
                    "required": ["list_id", "taskseries_id", "task_id", "tags"],
                },
            },
            {
                "name": "set_due_date",
                "description": "Set the due date of a task",
                "inputSchema": {
                    "type": "object",
                    "properties": {
                        "list_id": {"type": "string", "description": "List ID containing the task"},
                        "taskseries_id": {"type": "string", "description": "Task series ID"},
                        "task_id": {"type": "string", "description": "Task ID"},
                        "due": {
                            "type": "string",
                            "description": 'Due date (e.g., "today", "tomorrow", "next Friday", "2025-06-20", "tomorrow at 3pm") or empty string to clear',
                        },
                    },
                    "required": ["list_id", "taskseries_id", "task_id", "due"],
                },
            },
            {
                "name": "set_task_start_date",
                "description": "Set the start date of a task",
                "inputSchema": {
                    "type": "object",
                    "properties": {
                        "list_id": {"type": "string", "description": "List ID containing the task"},
                        "taskseries_id": {"type": "string", "description": "Task series ID"},
                        "task_id": {"type": "string", "description": "Task ID"},
                        "start": {
                            "type": "string",
                            "description": 'Start date (e.g., "today", "tomorrow", "next week", "2025-06-20") or empty string to clear',
                        },
                    },
                    "required": ["list_id", "taskseries_id", "task_id", "start"],
                },
            },
            {
                "name": "set_task_recurrence",
                "description": "Set a recurrence pattern for a task",
                "inputSchema": {
                    "type": "object",
                    "properties": {
                        "list_id": {"type": "string", "description": "List ID containing the task"},
                        "taskseries_id": {"type": "string", "description": "Task series ID"},
                        "task_id": {"type": "string", "description": "Task ID"},
                        "repeat": {
                            "type": "string",
                            "description": 'Recurrence pattern (e.g., "every day", "every week", "every 2 weeks", "every month", "every year")',
                        },
                    },
                    "required": ["list_id", "taskseries_id", "task_id", "repeat"],
                },
            },
            {
                "name": "clear_task_recurrence",
                "description": "Remove recurrence from a task",
                "inputSchema": {
                    "type": "object",
                    "properties": {
                        "list_id": {"type": "string", "description": "List ID containing the task"},
                        "taskseries_id": {"type": "string", "description": "Task series ID"},
                        "task_id": {"type": "string", "description": "Task ID"},
                    },
                    "required": ["list_id", "taskseries_id", "task_id"],
                },
            },
            {
                "name": "archive_list",
                "description": "Archive a list",
                "inputSchema": {
                    "type": "object",
                    "properties": {"list_id": {"type": "string", "description": "List ID to archive"}},
                    "required": ["list_id"],
                },
            },
            {
                "name": "add_task_note",
                "description": "Add a note to a task",
                "inputSchema": {
                    "type": "object",
                    "properties": {
                        "list_id": {"type": "string", "description": "List ID containing the task"},
                        "taskseries_id": {"type": "string", "description": "Task series ID"},
                        "task_id": {"type": "string", "description": "Task ID"},
                        "text": {"type": "string", "description": "Note content (required)"},
                        "title": {"type": "string", "description": "Note title (optional)"},
                    },
                    "required": ["list_id", "taskseries_id", "task_id", "text"],
                },
            },
            {
                "name": "edit_task_note",
                "description": "Edit an existing note",
                "inputSchema": {
                    "type": "object",
                    "properties": {
                        "note_id": {"type": "string", "description": "Note ID to edit"},
                        "text": {"type": "string", "description": "Updated note content"},
                        "title": {"type": "string", "description": "Updated note title (optional)"},
                    },
                    "required": ["note_id", "text"],
                },
            },
            {
                "name": "delete_task_note",
                "description": "Delete a note from a task",
                "inputSchema": {
                    "type": "object",
                    "properties": {"note_id": {"type": "string", "description": "Note ID to delete"}},
                    "required": ["note_id"],
                },
            },
            {
                "name": "read_task_notes",
                "description": "Read all notes for a task",
                "inputSchema": {
                    "type": "object",
                    "properties": {
                        "list_id": {"type": "string", "description": "List ID containing the task"},
                        "taskseries_id": {"type": "string", "description": "Task series ID"},
                        "task_id": {"type": "string", "description": "Task ID"},
                    },
                    "required": ["list_id", "taskseries_id", "task_id"],
                },
            },
            {
                "name": "create_subtask",
                "description": "Create a subtask (RTM Pro feature)",
                "inputSchema": {
                    "type": "object",
                    "properties": {
                        "name": {"type": "string", "description": "Subtask name"},
                        "parent_list_id": {"type": "string", "description": "List ID of the parent task"},
                        "parent_taskseries_id": {"type": "string", "description": "Task series ID of the parent task"},
                        "parent_task_id": {"type": "string", "description": "Task ID of the parent task"},
                    },
                    "required": ["name", "parent_list_id", "parent_taskseries_id", "parent_task_id"],
                },
            },
            {
                "name": "list_subtasks",
                "description": "List all subtasks of a parent task (limited functionality - see output for details)",
                "inputSchema": {
                    "type": "object",
                    "properties": {
                        "parent_list_id": {"type": "string", "description": "List ID of the parent task"},
                        "parent_taskseries_id": {"type": "string", "description": "Task series ID of the parent task"},
                        "parent_name": {
                            "type": "string",
                            "description": "Name of the parent task (optional, helps identify subtasks)",
                        },
                    },
                    "required": ["parent_list_id", "parent_taskseries_id"],
                },
            },
            {
                "name": "move_task",
                "description": "Move a task to a different list",
                "inputSchema": {
                    "type": "object",
                    "properties": {
                        "list_id": {"type": "string", "description": "List ID containing the task"},
                        "taskseries_id": {"type": "string", "description": "Task series ID"},
                        "task_id": {"type": "string", "description": "Task ID"},
                        "to_list_id": {
                            "type": "string",
                            "description": "Destination list ID to move the task to",
                        },
                    },
                    "required": ["list_id", "taskseries_id", "task_id", "to_list_id"],
                },
            },
            {
                "name": "postpone_task",
                "description": "Postpone a task (delays the due date)",
                "inputSchema": {
                    "type": "object",
                    "properties": {
                        "list_id": {"type": "string", "description": "List ID containing the task"},
                        "taskseries_id": {"type": "string", "description": "Task series ID"},
                        "task_id": {"type": "string", "description": "Task ID"},
                    },
                    "required": ["list_id", "taskseries_id", "task_id"],
                },
            },
            {
                "name": "set_task_estimate",
                "description": "Set or clear the time estimate for a task",
                "inputSchema": {
                    "type": "object",
                    "properties": {
                        "list_id": {"type": "string", "description": "List ID containing the task"},
                        "taskseries_id": {"type": "string", "description": "Task series ID"},
                        "task_id": {"type": "string", "description": "Task ID"},
                        "estimate": {
                            "type": "string",
                            "description": 'Time estimate (e.g., "30 minutes", "2 hours", "1 day", "30m", "2h", "1d") or empty string to clear',
                        },
                    },
                    "required": ["list_id", "taskseries_id", "task_id", "estimate"],
                },
            },
            {
                "name": "set_task_name",
                "description": "Rename a task",
                "inputSchema": {
                    "type": "object",
                    "properties": {
                        "list_id": {"type": "string", "description": "List ID containing the task"},
                        "taskseries_id": {"type": "string", "description": "Task series ID"},
                        "task_id": {"type": "string", "description": "Task ID"},
                        "name": {"type": "string", "description": "New name for the task"},
                    },
                    "required": ["list_id", "taskseries_id", "task_id", "name"],
                },
            },
            {
                "name": "get_task_permalink",
                "description": "Get the RTM web permalink for a specific task",
                "inputSchema": {
                    "type": "object",
                    "properties": {"task_id": {"type": "string", "description": "Task ID to generate permalink for"}},
                    "required": ["task_id"],
                },
            },
            {
                "name": "get_locations",
                "description": "Get list of predefined locations from RTM account",
                "inputSchema": {"type": "object", "properties": {}, "required": []},
            },
            {
                "name": "set_task_location",
                "description": "Set or update the location for a task",
                "inputSchema": {
                    "type": "object",
                    "properties": {
                        "list_id": {"type": "string", "description": "List ID containing the task"},
                        "taskseries_id": {"type": "string", "description": "Task series ID"},
                        "task_id": {"type": "string", "description": "Task ID"},
                        "location": {
                            "type": "string",
                            "description": 'Location text (e.g., "Portland, OR", "Home office") or empty string to clear',
                        },
                    },
                    "required": ["list_id", "taskseries_id", "task_id", "location"],
                },
            },
            {
                "name": "set_task_url",
                "description": "Set or update the URL for a task",
                "inputSchema": {
                    "type": "object",
                    "properties": {
                        "list_id": {"type": "string", "description": "List ID containing the task"},
                        "taskseries_id": {"type": "string", "description": "Task series ID"},
                        "task_id": {"type": "string", "description": "Task ID"},
                        "url": {
                            "type": "string",
                            "description": "URL (e.g., https://example.com) or empty string to clear",
                        },
                    },
                    "required": ["list_id", "taskseries_id", "task_id", "url"],
                },
            },
        ]

    def handle_request(self, request: Dict[str, Any]) -> Optional[Dict[str, Any]]:
        """
        Handle MCP protocol requests.

        Args:
            request: JSON-RPC request from client

        Returns:
            Response to send back to client
        """
        method = request.get("method")
        print(f"Handling method: {method}", file=sys.stderr)

        if method == "initialize":
            return {
                "protocolVersion": "2024-11-05",
                "capabilities": {"tools": {}},
                "serverInfo": {"name": "rtm-mcp", "version": "0.1.0"},
            }
        elif method == "tools/list":
            return {"tools": self.tools}
        elif method == "tools/call":
            return self._handle_tool_call(request.get("params", {}))
        elif method == "notifications/initialized":
            # Client notification that initialization is complete
            return None
        else:
            return {"error": {"code": -32601, "message": "Method not found"}}

    def _handle_tool_call(self, params: Dict[str, Any]) -> Dict[str, Any]:
        """
        Handle a tool call request.

        Args:
            params: Tool call parameters with name and arguments

        Returns:
            Tool call result
        """
        tool_name = params.get("name")
        args = params.get("arguments", {})

        # Dispatch to tool implementation
        result = self._dispatch_tool(tool_name, args)

        if isinstance(result, dict) and "error" in result:
            return result

        return {"content": [{"type": "text", "text": result}]}

    def _dispatch_tool(self, tool_name: str, args: Dict[str, Any]) -> str | Dict[str, Any]:
        """
        Dispatch tool calls to their implementations.

        Args:
            tool_name: Name of the tool to call
            args: Arguments for the tool

        Returns:
            Tool result as string or error dict
        """
        if tool_name == "test_connection":
            return self._test_connection()
        elif tool_name == "list_all_lists":
            return self._list_all_lists()
        elif tool_name == "create_list":
            return self._create_list(args.get("name"))
        elif tool_name == "list_tasks":
            return self._list_tasks(
                args.get("list_id"), args.get("filter"), args.get("show_ids", False)
            )
        elif tool_name == "create_task":
            return self._create_task(
                args.get("name"),
                args.get("list_id"),
                args.get("due"),
                args.get("priority"),
                args.get("tags"),
            )
        elif tool_name == "complete_task":
            return self._complete_task(
                args.get("list_id"), args.get("taskseries_id"), args.get("task_id")
            )
        elif tool_name == "delete_task":
            return self._delete_task(
                args.get("list_id"), args.get("taskseries_id"), args.get("task_id")
            )
        elif tool_name == "set_task_priority":
            return self._set_task_priority(
                args.get("list_id"),
                args.get("taskseries_id"),
                args.get("task_id"),
                args.get("priority"),
            )
        elif tool_name == "add_task_tags":
            return self._add_task_tags(
                args.get("list_id"), args.get("taskseries_id"), args.get("task_id"), args.get("tags")
            )
        elif tool_name == "remove_task_tags":
            return self._remove_task_tags(
                args.get("list_id"), args.get("taskseries_id"), args.get("task_id"), args.get("tags")
            )
        elif tool_name == "set_due_date":
            return self._set_due_date(
                args.get("list_id"), args.get("taskseries_id"), args.get("task_id"), args.get("due")
            )
        elif tool_name == "set_task_start_date":
            return self._set_task_start_date(
                args.get("list_id"),
                args.get("taskseries_id"),
                args.get("task_id"),
                args.get("start"),
            )
        elif tool_name == "set_task_recurrence":
            return self._set_task_recurrence(
                args.get("list_id"),
                args.get("taskseries_id"),
                args.get("task_id"),
                args.get("repeat"),
            )
        elif tool_name == "clear_task_recurrence":
            return self._clear_task_recurrence(
                args.get("list_id"), args.get("taskseries_id"), args.get("task_id")
            )
        elif tool_name == "archive_list":
            return self._archive_list(args.get("list_id"))
        elif tool_name == "add_task_note":
            return self._add_task_note(
                args.get("list_id"),
                args.get("taskseries_id"),
                args.get("task_id"),
                args.get("text"),
                args.get("title"),
            )
        elif tool_name == "edit_task_note":
            return self._edit_task_note(args.get("note_id"), args.get("text"), args.get("title"))
        elif tool_name == "delete_task_note":
            return self._delete_task_note(args.get("note_id"))
        elif tool_name == "read_task_notes":
            return self._read_task_notes(
                args.get("list_id"), args.get("taskseries_id"), args.get("task_id")
            )
        elif tool_name == "create_subtask":
            return self._create_subtask(
                args.get("name"),
                args.get("parent_list_id"),
                args.get("parent_taskseries_id"),
                args.get("parent_task_id"),
            )
        elif tool_name == "list_subtasks":
            return self._list_subtasks(
                args.get("parent_list_id"),
                args.get("parent_taskseries_id"),
                args.get("parent_name"),
            )
        elif tool_name == "move_task":
            return self._move_task(
                args.get("list_id"),
                args.get("taskseries_id"),
                args.get("task_id"),
                args.get("to_list_id"),
            )
        elif tool_name == "postpone_task":
            return self._postpone_task(
                args.get("list_id"), args.get("taskseries_id"), args.get("task_id")
            )
        elif tool_name == "set_task_estimate":
            return self._set_task_estimate(
                args.get("list_id"),
                args.get("taskseries_id"),
                args.get("task_id"),
                args.get("estimate"),
            )
        elif tool_name == "set_task_name":
            return self._set_task_name(
                args.get("list_id"),
                args.get("taskseries_id"),
                args.get("task_id"),
                args.get("name"),
            )
        elif tool_name == "get_task_permalink":
            return self._get_task_permalink(args.get("task_id"))
        elif tool_name == "get_locations":
            return self._get_locations()
        elif tool_name == "set_task_location":
            return self._set_task_location(
                args.get("list_id"),
                args.get("taskseries_id"),
                args.get("task_id"),
                args.get("location"),
            )
        elif tool_name == "set_task_url":
            return self._set_task_url(
                args.get("list_id"),
                args.get("taskseries_id"),
                args.get("task_id"),
                args.get("url"),
            )
        else:
            return {"error": {"code": -32602, "message": f"Unknown tool: {tool_name}"}}

    # Tool implementations - stubbed for now, will implement below
    def _test_connection(self) -> str:
        """Test RTM API connection."""
        result = self.rtm.call_method("rtm.test.echo", {"test": "hello"})

        if result.get("error") or result.get("rsp", {}).get("stat") == "fail":
            error_msg = (
                result.get("error") or result.get("rsp", {}).get("err", {}).get("msg") or "Unknown error"
            )
            return f"❌ RTM API Error: {error_msg}"
        else:
            return f"✅ RTM API connection successful!\n\nResponse: {json.dumps(result, indent=2)}"

    def _list_all_lists(self) -> str:
        """List all RTM lists."""
        result = self.rtm.call_method("rtm.lists.getList")

        if result.get("error") or result.get("rsp", {}).get("stat") == "fail":
            error_msg = (
                result.get("error") or result.get("rsp", {}).get("err", {}).get("msg") or "Unknown error"
            )
            return f"❌ RTM API Error: {error_msg}"
        else:
            lists = result.get("rsp", {}).get("lists", {}).get("list", [])
            if not isinstance(lists, list):
                lists = [lists] if lists else []

            list_text = "\n".join(
                f"• {list_item['name']} (ID: {list_item['id']})"
                + (" [archived]" if list_item.get("archived") == "1" else "")
                + (" [smart]" if list_item.get("smart") == "1" else "")
                for list_item in lists
            )

            return f"📝 RTM Lists:\n\n{list_text}"

    def _create_list(self, name: Optional[str]) -> str:
        """Create a new list."""
        if not name:
            return "Error: List name is required"

        result = self.rtm.call_method("rtm.lists.add", {"name": name})

        if result.get("error") or result.get("rsp", {}).get("stat") == "fail":
            error_msg = (
                result.get("error") or result.get("rsp", {}).get("err", {}).get("msg") or "Unknown error"
            )
            return f"❌ RTM API Error: {error_msg}"
        else:
            list_item = result.get("rsp", {}).get("list")
            if list_item:
                return f"✅ Created list: {list_item['name']} (ID: {list_item['id']})"
            else:
                return "✅ List created successfully"

    def _get_list_name(self, list_id: Optional[str]) -> str:
        """Get list name by ID with caching."""
        if not list_id:
            return "Default List"

        # Load list cache if not already loaded
        if self.list_cache is None:
            result = self.rtm.call_method("rtm.lists.getList")

            if result.get("error") or result.get("rsp", {}).get("stat") == "fail":
                return "Unknown List"
            else:
                lists = result.get("rsp", {}).get("lists", {}).get("list", [])
                if not isinstance(lists, list):
                    lists = [lists] if lists else []

                # Create a hash for fast lookup
                self.list_cache = {list_item["id"]: list_item["name"] for list_item in lists}

        # Look up the list name in cache
        return self.list_cache.get(list_id, "Unknown List")

    @staticmethod
    def _ensure_array(obj: Any) -> List[Any]:
        """Ensure object is an array."""
        if obj is None:
            return []
        return obj if isinstance(obj, list) else [obj]

    @staticmethod
    def _format_time(time_str: Optional[str]) -> str:
        """Format ISO timestamp to readable format."""
        if not time_str:
            return ""
        try:
            dt = datetime.fromisoformat(time_str.replace("Z", "+00:00"))
            return dt.strftime("%Y-%m-%d %H:%M")
        except Exception:
            return time_str or ""

    # Tool implementations
    def _list_tasks(
        self, list_id: Optional[str] = None, filter: Optional[str] = None, show_ids: bool = False
    ) -> str:
        """List tasks with filtering."""
        params = {"v": "2"}  # Use API v2 to get parent_task_id fields
        if list_id:
            params["list_id"] = list_id
        if filter:
            params["filter"] = filter

        result = self.rtm.call_method("rtm.tasks.getList", params)

        if result.get("error") or result.get("rsp", {}).get("stat") == "fail":
            error_msg = (
                result.get("error") or result.get("rsp", {}).get("err", {}).get("msg") or "Unknown error"
            )
            return f"❌ RTM API Error: {error_msg}"

        lists = result.get("rsp", {}).get("tasks", {}).get("list", [])
        if not isinstance(lists, list):
            lists = [lists] if lists else []

        output = []
        task_count = 0

        for list_item in lists:
            list_name = list_item.get("name", "Unknown List")
            taskseries = list_item.get("taskseries", [])
            if not isinstance(taskseries, list):
                taskseries = [taskseries] if taskseries else []

            if not taskseries:
                continue

            output.append(f"📋 **{list_name}**")

            for ts in taskseries:
                task_name = ts.get("name", "Unnamed")
                ts_id = ts.get("id")

                # Handle task being array or dict
                task_data = ts.get("task", [])
                if not isinstance(task_data, list):
                    task_data = [task_data] if task_data else []

                if not task_data:
                    continue

                task = task_data[0]
                task_id = task.get("id")
                due = task.get("due", "")
                priority = task.get("priority", "N")

                # Format priority
                if priority == "1":
                    priority_str = "🔴"
                elif priority == "2":
                    priority_str = "🟡"
                elif priority == "3":
                    priority_str = "🔵"
                else:
                    priority_str = "⚪"

                line = f"  {priority_str} {task_name}"
                if due:
                    line += f" (📅 {due})"
                if show_ids:
                    line += f" [ID: {ts_id}/{task_id}]"

                output.append(line)
                task_count += 1

        if not output:
            return "📋 No tasks found."

        result_text = "\n".join(output)
        return f"📋 **Tasks** ({task_count} total):\n\n{result_text}"

    def _create_task(
        self,
        name: Optional[str],
        list_id: Optional[str] = None,
        due: Optional[str] = None,
        priority: Optional[str] = None,
        tags: Optional[str] = None,
    ) -> str:
        """Create a new task."""
        if not name:
            return "Error: Task name is required"

        # Build Smart Add text with all metadata
        smart_add_text = name

        # Add due date to Smart Add text
        if due:
            smart_add_text += f" ^{due}"

        # Add priority to Smart Add text
        if priority:
            smart_add_text += f" !{priority}"

        # Add tags to Smart Add text
        if tags:
            for tag in tags.split(","):
                smart_add_text += f" #{tag.strip()}"

        # Create task using Smart Add with parse=1
        params = {"name": smart_add_text, "parse": "1"}
        if list_id:
            params["list_id"] = list_id

        result = self.rtm.call_method("rtm.tasks.add", params)

        if result.get("error") or result.get("rsp", {}).get("stat") == "fail":
            error_msg = (
                result.get("error") or result.get("rsp", {}).get("err", {}).get("msg") or "Unknown error"
            )
            return f"❌ RTM API Error: {error_msg}"

        # Extract the created task info
        rsp = result.get("rsp", {})
        list_item = rsp.get("list", {})
        taskseries = list_item.get("taskseries")
        if not taskseries:
            return "❌ Task created but couldn't parse response"

        # Handle taskseries being array or dict
        if isinstance(taskseries, list):
            ts = taskseries[0]
        else:
            ts = taskseries

        task_name = ts.get("name", name)
        actual_list_id = list_item.get("id")
        list_name = self._get_list_name(actual_list_id)
        ts_id = ts.get("id")

        # Handle task being array or dict
        task_data = ts.get("task", {})
        if isinstance(task_data, list):
            task = task_data[0]
        else:
            task = task_data

        task_id = task.get("id")

        # Build response
        response_parts = [f"✅ Created task: {task_name} in {list_name}"]
        response_parts.append(f"   IDs: list={actual_list_id}, series={ts_id}, task={task_id}")

        # Show applied metadata
        metadata_applied = []

        if task.get("due"):
            has_time = task.get("has_due_time") == "1"
            time_info = " (includes time)" if has_time else " (date only)"
            metadata_applied.append(f"📅 Due: {task.get('due')}{time_info}")

        if task.get("priority") and task.get("priority") not in ("N", ""):
            priority_map = {"1": "🔴 High", "2": "🟡 Medium", "3": "🔵 Low"}
            metadata_applied.append(f"Priority: {priority_map.get(task.get('priority'), task.get('priority'))}")

        if ts.get("tags"):
            tags_data = ts["tags"]
            if isinstance(tags_data, dict) and tags_data.get("tag"):
                tag_list = tags_data["tag"]
                if not isinstance(tag_list, list):
                    tag_list = [tag_list]
                if tag_list:
                    metadata_applied.append(f"🏷️ Tags: {', '.join(tag_list)}")

        response_parts.extend(metadata_applied)
        return "\n".join(response_parts)

    def _complete_task(self, list_id: str, taskseries_id: str, task_id: str) -> str:
        """Complete a task."""
        if not (list_id and taskseries_id and task_id):
            return "Error: list_id, taskseries_id, and task_id are required"

        params = {"list_id": list_id, "taskseries_id": taskseries_id, "task_id": task_id}
        result = self.rtm.call_method("rtm.tasks.complete", params)

        if result.get("error") or result.get("rsp", {}).get("stat") == "fail":
            error_msg = (
                result.get("error") or result.get("rsp", {}).get("err", {}).get("msg") or "Unknown error"
            )
            return f"❌ RTM API Error: {error_msg}"

        return "✅ Task completed successfully!"

    def _delete_task(self, list_id: str, taskseries_id: str, task_id: str) -> str:
        """Delete a task."""
        if not (list_id and taskseries_id and task_id):
            return "Error: list_id, taskseries_id, and task_id are required"

        params = {"list_id": list_id, "taskseries_id": taskseries_id, "task_id": task_id}
        result = self.rtm.call_method("rtm.tasks.delete", params)

        if result.get("error") or result.get("rsp", {}).get("stat") == "fail":
            error_msg = (
                result.get("error") or result.get("rsp", {}).get("err", {}).get("msg") or "Unknown error"
            )
            return f"❌ RTM API Error: {error_msg}"

        return "✅ Task deleted permanently!"

    def _set_task_priority(
        self, list_id: str, taskseries_id: str, task_id: str, priority: str
    ) -> str:
        """Set task priority."""
        if not (list_id and taskseries_id and task_id and priority is not None):
            return "Error: list_id, taskseries_id, task_id, and priority are required"

        if priority not in ("1", "2", "3", ""):
            return "Error: Priority must be '1' (High), '2' (Medium), '3' (Low), or '' (None)"

        params = {"list_id": list_id, "taskseries_id": taskseries_id, "task_id": task_id, "priority": priority}
        result = self.rtm.call_method("rtm.tasks.setPriority", params)

        if result.get("error") or result.get("rsp", {}).get("stat") == "fail":
            error_msg = (
                result.get("error") or result.get("rsp", {}).get("err", {}).get("msg") or "Unknown error"
            )
            return f"❌ RTM API Error: {error_msg}"

        # Extract priority from response
        list_data = result.get("rsp", {}).get("list")
        if list_data:
            if isinstance(list_data, list):
                list_data = list_data[0]

            taskseries = list_data.get("taskseries")
            if taskseries:
                if isinstance(taskseries, list):
                    taskseries = taskseries[0]

                task = taskseries.get("task")
                if task:
                    if isinstance(task, list):
                        task = task[0]

                    priority_map = {"1": "🔴 High", "2": "🟡 Medium", "3": "🔵 Low", "N": "None"}
                    return f"✅ Task priority set to: {priority_map.get(task.get('priority'), task.get('priority'))}"

        return "✅ Task priority updated successfully!"

    def _add_task_tags(self, list_id: str, taskseries_id: str, task_id: str, tags: str) -> str:
        """Add tags to task."""
        if not (list_id and taskseries_id and task_id and tags):
            return "Error: list_id, taskseries_id, task_id, and tags are required"

        params = {"list_id": list_id, "taskseries_id": taskseries_id, "task_id": task_id, "tags": tags}
        result = self.rtm.call_method("rtm.tasks.addTags", params)

        if result.get("error") or result.get("rsp", {}).get("stat") == "fail":
            error_msg = (
                result.get("error") or result.get("rsp", {}).get("err", {}).get("msg") or "Unknown error"
            )
            return f"❌ RTM API Error: {error_msg}"

        # Extract tags from response
        list_data = result.get("rsp", {}).get("list")
        if list_data:
            if isinstance(list_data, list):
                list_data = list_data[0]

            taskseries = list_data.get("taskseries")
            if taskseries:
                if isinstance(taskseries, list):
                    taskseries = taskseries[0]

                tags_data = taskseries.get("tags", {})
                if isinstance(tags_data, dict) and tags_data.get("tag"):
                    tag_list = tags_data["tag"]
                    if not isinstance(tag_list, list):
                        tag_list = [tag_list]
                    tag_display = ", ".join(tag_list) if tag_list else "none"
                elif isinstance(tags_data, list):
                    tag_display = ", ".join(tags_data) if tags_data else "none"
                else:
                    tag_display = "none"

                return f"✅ Tags added! Current tags: {tag_display}"

        return "✅ Tags added successfully!"

    def _remove_task_tags(
        self, list_id: str, taskseries_id: str, task_id: str, tags: str
    ) -> str:
        """Remove tags from task."""
        if not (list_id and taskseries_id and task_id and tags):
            return "Error: list_id, taskseries_id, task_id, and tags are required"

        params = {"list_id": list_id, "taskseries_id": taskseries_id, "task_id": task_id, "tags": tags}
        result = self.rtm.call_method("rtm.tasks.removeTags", params)

        if result.get("error") or result.get("rsp", {}).get("stat") == "fail":
            error_msg = (
                result.get("error") or result.get("rsp", {}).get("err", {}).get("msg") or "Unknown error"
            )
            return f"❌ RTM API Error: {error_msg}"

        # Extract remaining tags from response
        list_data = result.get("rsp", {}).get("list")
        if list_data:
            if isinstance(list_data, list):
                list_data = list_data[0]

            taskseries = list_data.get("taskseries")
            if taskseries:
                if isinstance(taskseries, list):
                    taskseries = taskseries[0]

                tags_data = taskseries.get("tags", {})
                if isinstance(tags_data, dict) and tags_data.get("tag"):
                    tag_list = tags_data["tag"]
                    if not isinstance(tag_list, list):
                        tag_list = [tag_list]
                    tag_display = ", ".join(tag_list) if tag_list else "none"
                elif isinstance(tags_data, list):
                    tag_display = ", ".join(tags_data) if tags_data else "none"
                else:
                    tag_display = "none"

                return f"✅ Tags removed! Current tags: {tag_display}"

        return "✅ Tags removed successfully!"

    def _set_due_date(
        self, list_id: str, taskseries_id: str, task_id: str, due: str
    ) -> str:
        """Set due date."""
        if not (list_id and taskseries_id and task_id and due is not None):
            return "Error: list_id, taskseries_id, task_id, and due are required"

        params = {
            "list_id": list_id,
            "taskseries_id": taskseries_id,
            "task_id": task_id,
            "due": due,
            "parse": "1",
        }

        result = self.rtm.call_method("rtm.tasks.setDueDate", params)

        if result.get("error") or result.get("rsp", {}).get("stat") == "fail":
            error_msg = (
                result.get("rsp", {}).get("err", {}).get("msg")
                or result.get("error")
                or "Unknown error"
            )
            return f"Error setting due date: {error_msg}"

        # Extract updated task info
        list_item = result.get("rsp", {}).get("list")
        if not list_item:
            return "✅ Due date updated successfully!"

        taskseries = list_item.get("taskseries")
        if taskseries:
            if isinstance(taskseries, list):
                ts = taskseries[0]
            else:
                ts = taskseries

            task = ts.get("task")
            if task:
                if isinstance(task, list):
                    task = task[0]

            task_name = ts.get("name")

            if not due:
                return f"✅ Due date cleared for: {task_name}"

            due_value = task.get("due", "")
            has_time = task.get("has_due_time") == "1"
            time_info = " (includes time)" if has_time else " (date only)"

            if due_value:
                return f"✅ Due date set for: {task_name}\n📅 Due: {due_value}{time_info}"

        return "✅ Due date set successfully!"

    def _set_task_start_date(
        self, list_id: str, taskseries_id: str, task_id: str, start: str
    ) -> str:
        """Set start date."""
        if not (list_id and taskseries_id and task_id and start is not None):
            return "Error: list_id, taskseries_id, task_id, and start are required"

        params = {
            "list_id": list_id,
            "taskseries_id": taskseries_id,
            "task_id": task_id,
            "start": start,
            "parse": "1",
            "v": "2",  # API version 2 required for setStartDate
        }

        result = self.rtm.call_method("rtm.tasks.setStartDate", params)

        if result.get("error") or result.get("rsp", {}).get("stat") == "fail":
            error_msg = (
                result.get("rsp", {}).get("err", {}).get("msg")
                or result.get("error")
                or "Unknown error"
            )
            return f"Error setting start date: {error_msg}"

        # Extract updated task info
        list_item = result.get("rsp", {}).get("list")
        if not list_item:
            return "✅ Start date updated successfully!"

        taskseries = list_item.get("taskseries")
        if taskseries:
            if isinstance(taskseries, list):
                ts = taskseries[0]
            else:
                ts = taskseries

            task = ts.get("task")
            if task:
                if isinstance(task, list):
                    task = task[0]

            task_name = ts.get("name")

            if not start:
                return f"✅ Start date cleared for: {task_name}"

            start_value = task.get("start", "")
            has_time = task.get("has_start_time") == "1"
            time_info = " (includes time)" if has_time else " (date only)"

            if start_value:
                return f"✅ Start date set for: {task_name}\n🏁 Start: {start_value}{time_info}"

        return "✅ Start date set successfully!"

    def _set_task_recurrence(
        self, list_id: str, taskseries_id: str, task_id: str, repeat: str
    ) -> str:
        """Set task recurrence."""
        if not (list_id and taskseries_id and task_id and repeat):
            return "Error: list_id, taskseries_id, task_id, and repeat are required"

        params = {
            "list_id": list_id,
            "taskseries_id": taskseries_id,
            "task_id": task_id,
            "repeat": repeat,
        }

        result = self.rtm.call_method("rtm.tasks.setRecurrence", params)

        if result.get("error") or result.get("rsp", {}).get("stat") == "fail":
            error_msg = (
                result.get("rsp", {}).get("err", {}).get("msg")
                or result.get("error")
                or "Unknown error"
            )
            return f"❌ Error setting recurrence: {error_msg}"

        return f"✅ Task recurrence set to: {repeat}"

    def _clear_task_recurrence(self, list_id: str, taskseries_id: str, task_id: str) -> str:
        """Clear task recurrence."""
        if not (list_id and taskseries_id and task_id):
            return "Error: list_id, taskseries_id, and task_id are required"

        params = {"list_id": list_id, "taskseries_id": taskseries_id, "task_id": task_id}

        result = self.rtm.call_method("rtm.tasks.setRecurrence", params)

        if result.get("error") or result.get("rsp", {}).get("stat") == "fail":
            error_msg = (
                result.get("rsp", {}).get("err", {}).get("msg")
                or result.get("error")
                or "Unknown error"
            )
            return f"❌ Error clearing recurrence: {error_msg}"

        return "✅ Task recurrence cleared!"

    def _archive_list(self, list_id: str) -> str:
        """Archive a list."""
        if not list_id:
            return "Error: list_id is required"

        result = self.rtm.call_method("rtm.lists.archive", {"list_id": list_id})

        if result.get("error") or result.get("rsp", {}).get("stat") == "fail":
            error_msg = (
                result.get("error") or result.get("rsp", {}).get("err", {}).get("msg") or "Unknown error"
            )
            return f"❌ RTM API Error: {error_msg}"

        return "✅ List archived successfully!"

    def _add_task_note(
        self,
        list_id: str,
        taskseries_id: str,
        task_id: str,
        text: str,
        title: Optional[str] = None,
    ) -> str:
        """Add note to task."""
        if not (list_id and taskseries_id and task_id and text):
            return "Error: list_id, taskseries_id, task_id, and text are required"

        params = {
            "list_id": list_id,
            "taskseries_id": taskseries_id,
            "task_id": task_id,
            "note_body": text,
        }
        if title:
            params["note_title"] = title

        result = self.rtm.call_method("rtm.tasks.notes.add", params)

        if result.get("error") or result.get("rsp", {}).get("stat") == "fail":
            error_msg = (
                result.get("error") or result.get("rsp", {}).get("err", {}).get("msg") or "Unknown error"
            )
            return f"❌ Error adding note: {error_msg}"

        return "✅ Note added successfully!"

    def _edit_task_note(self, note_id: str, text: str, title: Optional[str] = None) -> str:
        """Edit a note."""
        if not (note_id and text):
            return "Error: note_id and text are required"

        params = {"note_id": note_id, "note_body": text}
        if title:
            params["note_title"] = title

        result = self.rtm.call_method("rtm.tasks.notes.edit", params)

        if result.get("error") or result.get("rsp", {}).get("stat") == "fail":
            error_msg = (
                result.get("error") or result.get("rsp", {}).get("err", {}).get("msg") or "Unknown error"
            )
            return f"❌ Error editing note: {error_msg}"

        return "✅ Note edited successfully!"

    def _delete_task_note(self, note_id: str) -> str:
        """Delete a note."""
        if not note_id:
            return "Error: note_id is required"

        result = self.rtm.call_method("rtm.tasks.notes.delete", {"note_id": note_id})

        if result.get("error") or result.get("rsp", {}).get("stat") == "fail":
            error_msg = (
                result.get("error") or result.get("rsp", {}).get("err", {}).get("msg") or "Unknown error"
            )
            return f"❌ Error deleting note: {error_msg}"

        return "✅ Note deleted successfully!"

    def _read_task_notes(self, list_id: str, taskseries_id: str, task_id: str) -> str:
        """Read task notes."""
        if not (list_id and taskseries_id and task_id):
            return "Error: list_id, taskseries_id, and task_id are required"

        result = self.rtm.call_method(
            "rtm.tasks.notes.getList", {"list_id": list_id, "taskseries_id": taskseries_id, "task_id": task_id}
        )

        if result.get("error") or result.get("rsp", {}).get("stat") == "fail":
            error_msg = (
                result.get("error") or result.get("rsp", {}).get("err", {}).get("msg") or "Unknown error"
            )
            return f"❌ Error reading notes: {error_msg}"

        # Extract notes
        taskseries = result.get("rsp", {}).get("taskseries")
        if not taskseries:
            return "📝 No notes found for this task"

        if isinstance(taskseries, list):
            taskseries = taskseries[0]

        notes_data = taskseries.get("notes", {}).get("note")
        if not notes_data:
            return "📝 No notes found for this task"

        if not isinstance(notes_data, list):
            notes_data = [notes_data]

        output = []
        for index, note in enumerate(notes_data):
            output.append(f"**Note {index + 1}** (ID: {note.get('id')})")
            if note.get("title"):
                output.append(f"Title: {note.get('title')}")
            output.append(f"Created: {self._format_time(note.get('created'))}")
            if note.get("modified") != note.get("created"):
                output.append(f"Modified: {self._format_time(note.get('modified'))}")
            output.append("")
            output.append(note.get("$t", ""))
            output.append("")
            if index < len(notes_data) - 1:
                output.append("---")

        return "\n".join(output).strip()

    def _create_subtask(
        self,
        name: str,
        parent_list_id: str,
        parent_taskseries_id: str,
        parent_task_id: str,
    ) -> str:
        """Create a subtask."""
        if not (name and parent_list_id and parent_taskseries_id and parent_task_id):
            return "Error: name, parent_list_id, parent_taskseries_id, and parent_task_id are required"

        # Step 1: Create the task
        create_params = {"name": name, "list_id": parent_list_id}
        create_result = self.rtm.call_method("rtm.tasks.add", create_params)

        if create_result.get("error") or create_result.get("rsp", {}).get("stat") == "fail":
            error_msg = (
                create_result.get("error")
                or create_result.get("rsp", {}).get("err", {}).get("msg")
                or "Unknown error"
            )
            return f"❌ Error creating task: {error_msg}"

        # Extract created task info
        list_item = create_result.get("rsp", {}).get("list")
        taskseries = list_item.get("taskseries")
        if not taskseries:
            return "❌ Task created but couldn't parse response"

        if isinstance(taskseries, list):
            ts = taskseries[0]
        else:
            ts = taskseries

        task_data = ts.get("task")
        if not task_data:
            return "❌ Task created but couldn't parse response"

        if isinstance(task_data, list):
            task = task_data[0]
        else:
            task = task_data

        new_task_info = {
            "list_id": list_item.get("id"),
            "taskseries_id": ts.get("id"),
            "task_id": task.get("id"),
            "name": ts.get("name"),
        }

        # Step 2: Set it as a subtask
        set_parent_params = {
            "v": "2",
            "list_id": new_task_info["list_id"],
            "taskseries_id": new_task_info["taskseries_id"],
            "task_id": new_task_info["task_id"],
            "parent_task_id": parent_task_id,
        }

        set_parent_result = self.rtm.call_method("rtm.tasks.setParentTask", set_parent_params)

        if set_parent_result.get("error") or set_parent_result.get("rsp", {}).get("stat") == "fail":
            error_msg = (
                set_parent_result.get("error")
                or set_parent_result.get("rsp", {}).get("err", {}).get("msg")
                or "Unknown error"
            )
            return (
                f"⚠️ Task created but couldn't set as subtask: {error_msg}\n"
                f"Created task: {new_task_info['name']}\n"
                f"IDs: list={new_task_info['list_id']}, series={new_task_info['taskseries_id']}, task={new_task_info['task_id']}"
            )

        return (
            f"✅ Created subtask: {new_task_info['name']}\n"
            f"IDs: list={new_task_info['list_id']}, series={new_task_info['taskseries_id']}, task={new_task_info['task_id']}"
        )

    def _list_subtasks(
        self,
        parent_list_id: str,
        parent_taskseries_id: str,
        parent_name: Optional[str] = None,
    ) -> str:
        """List subtasks."""
        output = [
            "📋 **Subtasks Listing (Limited Functionality)**\n",
            "**Note**: RTM API doesn't expose parent-child relationships in task lists.",
            "This tool shows a workaround approach.\n",
        ]

        if parent_name:
            output.append(f"Parent task: {parent_name}")
        output.append(f"Parent IDs: list={parent_list_id}, series={parent_taskseries_id}\n")

        # Strategy 1: Check if parent has subtasks
        params = {"list_id": parent_list_id, "filter": "hasSubtasks:true"}
        result = self.rtm.call_method("rtm.tasks.getList", params)

        if result.get("rsp", {}).get("stat") == "ok":
            lists = result.get("rsp", {}).get("tasks", {}).get("list")
            if lists:
                if not isinstance(lists, list):
                    lists = [lists]

                parent_found = False
                for list_item in lists:
                    taskseries = list_item.get("taskseries")
                    if taskseries:
                        if not isinstance(taskseries, list):
                            taskseries = [taskseries]

                        for ts in taskseries:
                            if ts.get("id") == parent_taskseries_id:
                                parent_found = True
                                output.append("✅ Parent task confirmed to have subtasks\n")
                                break

                if not parent_found:
                    output.append("⚠️ This task doesn't appear to have any subtasks\n")
                    return "\n".join(output)

        # Strategy 2: List all tasks and suggest manual identification
        output.append(
            "\n**Workaround**: Here are all incomplete tasks in the list."
            "\nSubtasks typically appear after their parent in RTM:\n"
        )

        all_params = {"list_id": parent_list_id, "filter": "status:incomplete"}
        all_result = self.rtm.call_method("rtm.tasks.getList", all_params)

        if all_result.get("rsp", {}).get("stat") == "ok":
            lists = all_result.get("rsp", {}).get("tasks", {}).get("list")
            if lists:
                if not isinstance(lists, list):
                    lists = [lists]

                found_parent = False
                task_count = 0

                for list_item in lists:
                    taskseries = list_item.get("taskseries")
                    if taskseries:
                        if not isinstance(taskseries, list):
                            taskseries = [taskseries]

                        for ts in taskseries:
                            task = ts.get("task")
                            if not isinstance(task, list):
                                task = [task] if task else []

                            for t in task:
                                if t.get("completed"):
                                    continue

                                if ts.get("id") == parent_taskseries_id:
                                    found_parent = True
                                    output.append(f"\n**→ Parent: {ts.get('name')}** ⬇️")
                                elif found_parent and task_count < 10:
                                    output.append(f"  🔲 {ts.get('name')}")
                                    task_count += 1

                if task_count > 0:
                    output.append("\n(Showing up to 10 tasks after parent - subtasks typically appear here)")

        output.append("\n\n💡 **Tip**: Use the RTM website or app to see proper subtask hierarchy.")
        return "\n".join(output)

    def _move_task(self, list_id: str, taskseries_id: str, task_id: str, to_list_id: str) -> str:
        """Move task to another list."""
        if not (list_id and taskseries_id and task_id and to_list_id):
            return "Error: list_id, taskseries_id, task_id, and to_list_id are required"

        params = {
            "from_list_id": list_id,
            "taskseries_id": taskseries_id,
            "task_id": task_id,
            "to_list_id": to_list_id,
        }

        result = self.rtm.call_method("rtm.tasks.moveTo", params)

        if result.get("error") or result.get("rsp", {}).get("stat") == "fail":
            error_msg = (
                result.get("error")
                or result.get("rsp", {}).get("err", {}).get("msg")
                or "Unknown error"
            )
            return f"❌ RTM API Error: {error_msg}"

        # Get the destination list name
        to_list_name = self._get_list_name(to_list_id)

        # Extract task name from response if available
        list_data = result.get("rsp", {}).get("list")
        task_name = "Task"

        if list_data:
            if isinstance(list_data, list):
                list_data = list_data[0]

            taskseries = list_data.get("taskseries")
            if taskseries:
                if isinstance(taskseries, list):
                    taskseries = taskseries[0]
                task_name = taskseries.get("name", task_name)

        return f"✅ Task '{task_name}' moved to {to_list_name}"

    def _postpone_task(self, list_id: str, taskseries_id: str, task_id: str) -> str:
        """Postpone a task."""
        if not (list_id and taskseries_id and task_id):
            return "Error: list_id, taskseries_id, and task_id are required"

        params = {"list_id": list_id, "taskseries_id": taskseries_id, "task_id": task_id}
        result = self.rtm.call_method("rtm.tasks.postpone", params)

        if result.get("error") or result.get("rsp", {}).get("stat") == "fail":
            error_msg = (
                result.get("error")
                or result.get("rsp", {}).get("err", {}).get("msg")
                or "Unknown error"
            )
            return f"❌ RTM API Error: {error_msg}"

        # Extract task name and new due date from response
        list_data = result.get("rsp", {}).get("list")
        task_name = "Task"
        new_due_date = None

        if list_data:
            if isinstance(list_data, list):
                list_data = list_data[0]

            taskseries = list_data.get("taskseries")
            if taskseries:
                if isinstance(taskseries, list):
                    taskseries = taskseries[0]
                task_name = taskseries.get("name", task_name)

                # Get due date from task
                task = taskseries.get("task")
                if task:
                    if isinstance(task, list):
                        task = task[0]
                    new_due_date = task.get("due") if task.get("due") else None

        if new_due_date:
            return f"✅ Task '{task_name}' postponed to {new_due_date}"
        else:
            return f"✅ Task '{task_name}' postponed"

    def _set_task_estimate(
        self, list_id: str, taskseries_id: str, task_id: str, estimate: str
    ) -> str:
        """Set task time estimate."""
        if not (list_id and taskseries_id and task_id and estimate is not None):
            return "Error: list_id, taskseries_id, task_id, and estimate are required"

        params = {
            "list_id": list_id,
            "taskseries_id": taskseries_id,
            "task_id": task_id,
            "estimate": estimate,
        }

        result = self.rtm.call_method("rtm.tasks.setEstimate", params)

        if result.get("error") or result.get("rsp", {}).get("stat") == "fail":
            error_msg = (
                result.get("rsp", {}).get("err", {}).get("msg")
                or result.get("error")
                or "Unknown error"
            )
            return f"Error setting estimate: {error_msg}"

        # Extract updated task info
        list_item = result.get("rsp", {}).get("list")
        if not list_item:
            return "✅ Estimate updated successfully!"

        taskseries = list_item.get("taskseries")
        if taskseries:
            if isinstance(taskseries, list):
                ts = taskseries[0]
            else:
                ts = taskseries

            task = ts.get("task")
            if task:
                if isinstance(task, list):
                    task = task[0]

            task_name = ts.get("name")

            if not estimate:
                return f"✅ Estimate cleared for: {task_name}"

            estimate_value = task.get("estimate", "")
            return f"✅ Estimate set for: {task_name}\n⏱️ Estimate: {estimate_value}"

        return "✅ Estimate set successfully!"

    def _set_task_name(self, list_id: str, taskseries_id: str, task_id: str, name: str) -> str:
        """Rename task."""
        if not (list_id and taskseries_id and task_id and name):
            return "Error: list_id, taskseries_id, task_id, and name are required"

        params = {"list_id": list_id, "taskseries_id": taskseries_id, "task_id": task_id, "name": name}
        result = self.rtm.call_method("rtm.tasks.setName", params)

        if result.get("error") or result.get("rsp", {}).get("stat") == "fail":
            error_msg = (
                result.get("rsp", {}).get("err", {}).get("msg")
                or result.get("error")
                or "Unknown error"
            )
            return f"Error renaming task: {error_msg}"

        # Extract updated task info
        list_item = result.get("rsp", {}).get("list")
        if list_item:
            taskseries = list_item.get("taskseries")
            if taskseries:
                if isinstance(taskseries, list):
                    ts = taskseries[0]
                else:
                    ts = taskseries

                new_name = ts.get("name")
                return f"✅ Task renamed to: {new_name}"

        return "✅ Task renamed successfully!"

    def _get_task_permalink(self, task_id: str) -> str:
        """Get task permalink."""
        if not task_id:
            return "Error: task_id is required"
        return f"🌐 RTM Permalink:\nhttps://www.rememberthemilk.com/app/#tasks/{task_id}"

    def _get_locations(self) -> str:
        """Get available locations."""
        result = self.rtm.call_method("rtm.locations.getList")

        if result.get("error") or result.get("rsp", {}).get("stat") == "fail":
            error_msg = (
                result.get("error") or result.get("rsp", {}).get("err", {}).get("msg") or "Unknown error"
            )
            return f"❌ Error getting locations: {error_msg}"

        locations = result.get("rsp", {}).get("locations", {}).get("location")

        if not locations:
            return "📍 No predefined locations found in your RTM account.\n\n💡 You can add locations in the RTM web interface under Settings > Locations."

        # Handle both single location (dict) and multiple locations (list)
        location_list = locations if isinstance(locations, list) else [locations]

        output = [f"📍 **Available Locations** ({len(location_list)} total):\n"]

        for index, location in enumerate(location_list, 1):
            output.append(f"{index}. **{location.get('name')}**")
            output.append(f"   ID: {location.get('id')}")
            if location.get("address"):
                output.append(f"   Address: {location.get('address')}")
            if location.get("latitude") and location.get("longitude"):
                output.append(f"   Coordinates: {location.get('latitude')}, {location.get('longitude')}")
            output.append("")

        output.append("💡 **Usage:** Use location names or IDs with set_task_location")
        output.append("🔧 **Debug:** RTM API returns these as predefined locations with IDs")

        return "\n".join(output)

    def _resolve_location_id(self, location_input: str) -> Optional[str]:
        """Resolve location name to location_id."""
        # If input looks like a numeric ID, use it directly
        if location_input.isdigit():
            return location_input

        # Otherwise, get locations and find matching name
        locations_result = self.rtm.call_method("rtm.locations.getList")

        if locations_result.get("error") or locations_result.get("rsp", {}).get("stat") == "fail":
            return None

        locations = locations_result.get("rsp", {}).get("locations", {}).get("location")
        if not locations:
            return None

        # Handle both single location and multiple locations
        location_list = locations if isinstance(locations, list) else [locations]

        # Find location by name (case-insensitive)
        for loc in location_list:
            if loc.get("name", "").lower() == location_input.lower():
                return loc.get("id")

        return None

    def _set_task_location(
        self, list_id: str, taskseries_id: str, task_id: str, location: str
    ) -> str:
        """Set task location."""
        if not (list_id and taskseries_id and task_id):
            return "Error: list_id, taskseries_id, and task_id are required"

        # If location is empty string, clear the location
        if not location:
            params = {
                "list_id": list_id,
                "taskseries_id": taskseries_id,
                "task_id": task_id,
                # No location_id parameter clears the location
            }
        else:
            # Convert location name to location_id if needed
            location_id = self._resolve_location_id(location)

            if not location_id:
                return f"❌ Error: Location '{location}' not found. Use get_locations to see available locations."

            params = {
                "list_id": list_id,
                "taskseries_id": taskseries_id,
                "task_id": task_id,
                "location_id": location_id,
            }

        result = self.rtm.call_method("rtm.tasks.setLocation", params)

        if result.get("error") or result.get("rsp", {}).get("stat") == "fail":
            error_msg = (
                result.get("error") or result.get("rsp", {}).get("err", {}).get("msg") or "Unknown error"
            )
            return f"❌ Error setting location: {error_msg}"

        # Extract updated task info
        list_item = result.get("rsp", {}).get("list")
        if not list_item:
            return "✅ Location updated successfully!"

        taskseries = list_item.get("taskseries")
        if taskseries:
            if isinstance(taskseries, list):
                ts = taskseries[0]
            else:
                ts = taskseries

            task_name = ts.get("name")

            if not location:
                return f"✅ Location cleared for: {task_name}"
            else:
                return f"✅ Location set for: {task_name}\n📍 Location: {location}"

        if not location:
            return "✅ Location cleared successfully!"
        else:
            return "✅ Location set successfully!"

    def _set_task_url(
        self, list_id: str, taskseries_id: str, task_id: str, url: str
    ) -> str:
        """Set task URL."""
        if not (list_id and taskseries_id and task_id):
            return "Error: list_id, taskseries_id, and task_id are required"

        # url parameter can be empty string to clear
        url = url or ""

        params = {
            "list_id": list_id,
            "taskseries_id": taskseries_id,
            "task_id": task_id,
            "url": url,
        }

        result = self.rtm.call_method("rtm.tasks.setURL", params)

        if result.get("error") or result.get("rsp", {}).get("stat") == "fail":
            error_msg = (
                result.get("error") or result.get("rsp", {}).get("err", {}).get("msg") or "Unknown error"
            )
            return f"Error setting URL: {error_msg}"

        # Extract updated task info
        list_item = result.get("rsp", {}).get("list")
        if not list_item:
            return "✅ URL updated successfully!"

        taskseries = list_item.get("taskseries")
        if taskseries:
            if isinstance(taskseries, list):
                ts = taskseries[0]
            else:
                ts = taskseries

            task_name = ts.get("name")

            if not url:
                return f"✅ URL cleared for: {task_name}"
            else:
                return f"✅ URL set for: {task_name}\n🔗 URL: {url}"

        if not url:
            return "✅ URL cleared successfully!"
        else:
            return "✅ URL set successfully!"