RescueTime MCP Server

Instructions

Implementation Reference

• src/rescuetime_mcp/server.py:94-136 (handler)

  Primary handler implementation for the get_productivity_trend tool. Decorated with @mcp.tool() for FastMCP registration. Fetches daily summaries via RescueTimeClient, generates visual trend bars using productivity_bar helper, computes averages, and formats output string.
  @mcp.tool() async def get_productivity_trend(days: int = 7) -> str: """Get productivity pulse trend for the last N days. Args: days: Number of days to look back (default: 7, max 14) Shows the daily productivity pulse with visual bars and calculates averages. Useful for identifying patterns and trends over time. """ try: client = RescueTimeClient() summaries = await client.get_daily_summary() if not summaries: return "No productivity data available." # Limit to requested days summaries = summaries[:min(days, len(summaries))] lines = [f"Productivity Trend (last {len(summaries)} days):", ""] for day in summaries: pulse = day.productivity_pulse bar = productivity_bar(pulse) date_short = day.date[5:] # MM-DD lines.append(f"{date_short}: {bar} {pulse:.0f} ({day.total_duration_formatted})") # Calculate averages if summaries: avg_pulse = sum(d.productivity_pulse for d in summaries) / len(summaries) avg_productive = sum(d.all_productive_percentage for d in summaries) / len(summaries) total_hours = sum(d.total_hours for d in summaries) lines.append("") lines.append(f"Average: {avg_pulse:.0f} pulse, {avg_productive:.0f}% productive") lines.append(f"Total logged: {format_hours_minutes(total_hours)}") return "\n".join(lines) except RescueTimeAuthError as e: return f"Authentication error: {e}" except RescueTimeAPIError as e: return f"API error: {e}"
• src/rescuetime_mcp/models.py:8-36 (schema)

  Pydantic model for DailySummary data structure, parsed from RescueTime API and used directly in the tool handler for trend computation.
  class DailySummary(BaseModel): """Daily summary from the Daily Summary Feed API.""" date: str productivity_pulse: float very_productive_percentage: float productive_percentage: float neutral_percentage: float distracting_percentage: float very_distracting_percentage: float all_productive_percentage: float all_distracting_percentage: float total_hours: float very_productive_hours: float productive_hours: float neutral_hours: float distracting_hours: float very_distracting_hours: float all_productive_hours: float all_distracting_hours: float total_duration_formatted: str very_productive_duration_formatted: str productive_duration_formatted: str neutral_duration_formatted: str distracting_duration_formatted: str very_distracting_duration_formatted: str all_productive_duration_formatted: str all_distracting_duration_formatted: str
• src/rescuetime_mcp/server.py:30-34 (helper)

  Helper function to generate visual progress bars for productivity pulse scores, used in the trend display.
  def productivity_bar(score: float, width: int = 10) -> str: """Create a visual bar for productivity score (0-100).""" filled = int(score * width / 100) return "\u2588" * filled + "\u2591" * (width - filled)
• src/rescuetime_mcp/client.py:84-95 (helper)

  RescueTimeClient.get_daily_summary method, the data source providing DailySummary list for the tool's trend analysis.
  async def get_daily_summary(self) -> list[DailySummary]: """Get daily summary feed (last 14 days of daily rollups). Returns productivity pulse, time by productivity level, and category breakdowns. """ data = await self._request("daily_summary_feed") if not data: return [] return [DailySummary.model_validate(day) for day in data]
• src/rescuetime_mcp/server.py:16-28 (helper)

  Formatting helpers for durations used in average total logged time output.
  def format_hours_minutes(hours: float) -> str: """Format hours as 'Xh Ym'.""" h = int(hours) m = int((hours - h) * 60) if h > 0: return f"{h}h {m}m" return f"{m}m" def format_duration(seconds: int) -> str: """Format seconds as 'Xh Ym'.""" return format_hours_minutes(seconds / 3600)