get_groups

Instructions

Implementation Reference

• src/rtm_mcp/tools/utilities.py:300-336 (handler)

  The actual implementation of the get_groups tool handler. It calls rtm.groups.getList API, processes groups and their contacts, and returns a formatted response with group id, name, and member_count.

  @mcp.tool()
  async def get_groups(ctx: Context) -> dict[str, Any]:
      """Get contact groups.
  
      Returns:
          List of groups with member counts
      """
      from ..client import RTMClient
  
      client: RTMClient = await get_client()
  
      result = await client.call("rtm.groups.getList")
  
      groups_data = result.get("groups", {}).get("group", [])
      if isinstance(groups_data, dict):
          groups_data = [groups_data]
  
      groups = []
      for group in groups_data:
          contacts = group.get("contacts", {}).get("contact", [])
          if isinstance(contacts, dict):
              contacts = [contacts]
  
          groups.append(
              {
                  "id": group.get("id"),
                  "name": group.get("name"),
                  "member_count": len(contacts),
              }
          )
  
      return build_response(
          data={
              "groups": groups,
              "count": len(groups),
          },
      )

• src/rtm_mcp/server.py:102-106 (registration)

  Registration of utility tools including get_groups via register_utility_tools(mcp, get_client) function call.

  # Register all tools
  register_task_tools(mcp, get_client)
  register_list_tools(mcp, get_client)
  register_note_tools(mcp, get_client)
  register_utility_tools(mcp, get_client)

• src/rtm_mcp/response_builder.py:7-35 (helper)

  The build_response helper function used by get_groups to structure its response with data and metadata.

  def build_response(
      data: dict[str, Any] | list[Any],
      analysis: dict[str, Any] | None = None,
      transaction_id: str | None = None,
  ) -> dict[str, Any]:
      """Build a consistent response structure.
  
      Args:
          data: The main response data
          analysis: Optional analysis/insights
          transaction_id: Optional transaction ID for undo support
  
      Returns:
          Structured response dict
      """
      response = {
          "data": data,
          "metadata": {
              "fetched_at": datetime.now().isoformat(),
          },
      }
  
      if analysis:
          response["analysis"] = analysis
  
      if transaction_id:
          response["metadata"]["transaction_id"] = transaction_id
  
      return response