get_lists

Instructions

Implementation Reference

• src/rtm_mcp/tools/lists.py:18-54 (handler)

  The handler function for the get_lists tool. Defined as an async function decorated with @mcp.tool() inside register_list_tools. It calls the RTM API method rtm.lists.getList, parses the response using parse_lists_response, filters based on include_archived and include_smart parameters, sorts by position, and returns a formatted response using build_response and format_list helpers.

  @mcp.tool()
  async def get_lists(
      ctx: Context,
      include_archived: bool = False,
      include_smart: bool = True,
  ) -> dict[str, Any]:
      """Get all RTM lists.
  
      Args:
          include_archived: Include archived lists (default: false)
          include_smart: Include smart lists (default: true)
  
      Returns:
          List of all lists with metadata
      """
      from ..client import RTMClient
  
      client: RTMClient = await get_client()
  
      result = await client.call("rtm.lists.getList")
      lists = parse_lists_response(result)
  
      # Filter based on preferences
      if not include_archived:
          lists = [lst for lst in lists if not lst["archived"]]
      if not include_smart:
          lists = [lst for lst in lists if not lst["smart"]]
  
      # Sort by position
      lists.sort(key=lambda x: (x["position"] if x["position"] >= 0 else 9999, x["name"]))
  
      return build_response(
          data={
              "lists": [format_list(lst) for lst in lists],
              "count": len(lists),
          },
      )

• src/rtm_mcp/server.py:103-104 (registration)

  Registration of all list tools (including get_lists) via register_list_tools(mcp, get_client) call in the main server module.

  register_task_tools(mcp, get_client)
  register_list_tools(mcp, get_client)

• src/rtm_mcp/response_builder.py:228-247 (helper)

  parse_lists_response helper function that parses the raw RTM API response (result['lists']['list']) into a structured list of dicts with id, name, deleted, locked, archived, position, smart, filter, and sort_order fields.

  def parse_lists_response(result: dict[str, Any]) -> list[dict[str, Any]]:
      """Parse RTM lists response."""
      lists = result.get("lists", {}).get("list", [])
      if isinstance(lists, dict):
          lists = [lists]
  
      return [
          {
              "id": lst.get("id"),
              "name": lst.get("name"),
              "deleted": lst.get("deleted") == "1",
              "locked": lst.get("locked") == "1",
              "archived": lst.get("archived") == "1",
              "position": int(lst.get("position", -1)),
              "smart": lst.get("smart") == "1",
              "filter": lst.get("filter"),
              "sort_order": lst.get("sort_order"),
          }
          for lst in lists
      ]

• src/rtm_mcp/response_builder.py:113-121 (helper)

  format_list helper function that formats a single list dict from RTM into a cleaner response format with id, name, smart (bool), archived (bool), and locked (bool).

  def format_list(lst: dict[str, Any]) -> dict[str, Any]:
      """Format a list for response."""
      return {
          "id": lst.get("id"),
          "name": lst.get("name"),
          "smart": lst.get("smart") == "1",
          "archived": lst.get("archived") == "1",
          "locked": lst.get("locked") == "1",
      }

• src/rtm_mcp/types.py:34-44 (schema)

  RTMList Pydantic model (schema) for type-safe representation of an RTM list, used as a data model for list-related tool responses.

  class RTMList(BaseModel):
      """An RTM list."""
  
      id: str
      name: str
      deleted: bool = False
      locked: bool = False
      archived: bool = False
      position: int = -1
      smart: bool = False
      sort_order: int | None = None