RescueTime MCP Server

Instructions

Implementation Reference

• src/rescuetime_mcp/server.py:192-241 (handler)

  The primary handler function for the 'get_category_breakdown' tool, decorated with @mcp.tool() for registration. It handles input date resolution, API call to fetch category data, computes visualizations and percentages, and returns a formatted string output.

  @mcp.tool()
  async def get_category_breakdown(date_str: str = "today") -> str:
      """Get time spent by category.
  
      Args:
          date_str: Date to query - 'today', 'yesterday', or 'YYYY-MM-DD'
  
      Shows high-level categories like Software Development, Communication,
      Reference & Learning, etc. with time and productivity classification.
      """
      try:
          client = RescueTimeClient()
          resolved_date = resolve_date(date_str)
  
          categories = await client.get_analytic_data(
              restrict_kind="category",
              perspective="rank",
              restrict_begin=resolved_date,
              restrict_end=resolved_date,
          )
  
          if not categories:
              return f"No category data for {resolved_date}."
  
          lines = [f"Category Breakdown ({resolved_date}):", ""]
  
          total_seconds = sum(c.time_seconds for c in categories)
  
          for cat in categories:
              duration = format_duration(cat.time_seconds)
              percentage = (cat.time_seconds / total_seconds * 100) if total_seconds > 0 else 0
              prod_label = cat.productivity_label
  
              # Visual bar based on percentage
              bar_len = int(percentage / 5)
              bar = "\u2588" * bar_len
  
              lines.append(f"{cat.name}")
              lines.append(f"  {bar} {duration} ({percentage:.0f}%) - {prod_label}")
  
          lines.append("")
          lines.append(f"Total: {format_duration(total_seconds)}")
  
          return "\n".join(lines)
  
      except RescueTimeAuthError as e:
          return f"Authentication error: {e}"
      except RescueTimeAPIError as e:
          return f"API error: {e}"