MCP Toggl Server

Instructions

Implementation Reference

• src/index.ts:582-615 (handler)

  The main handler function for the 'toggl_weekly_report' tool. It ensures cache is warm, fetches time entries for the specified week, hydrates them with metadata, calculates week boundaries, generates the report using generateWeeklyReport utility, and returns either JSON or formatted text based on input.

  case 'toggl_weekly_report': {
    await ensureCache();
    
    const weekOffset = (args?.week_offset as number) || 0;
    const entries = await api.getTimeEntriesForWeek(weekOffset);
    const hydrated = await cache.hydrateTimeEntries(entries);
    
    // Calculate week boundaries
    const today = new Date();
    const dayOfWeek = today.getDay();
    const diff = today.getDate() - dayOfWeek + (dayOfWeek === 0 ? -6 : 1);
    const monday = new Date(today.setDate(diff));
    monday.setDate(monday.getDate() + (weekOffset * 7));
    const sunday = new Date(monday);
    sunday.setDate(sunday.getDate() + 6);
    
    const report = generateWeeklyReport(monday, sunday, hydrated);
    
    if (args?.format === 'text') {
      return {
        content: [{
          type: 'text',
          text: formatReportForDisplay(report)
        }]
      };
    }
    
    return {
      content: [{
        type: 'text',
        text: JSON.stringify(report, null, 2)
      }]
    };
  }

• src/index.ts:247-264 (schema)

  Schema definition for the 'toggl_weekly_report' tool, including name, description, and input schema for parameters like week_offset and format.

  {
    name: 'toggl_weekly_report',
    description: 'Generate a weekly report with daily breakdown and project summaries',
    inputSchema: {
      type: 'object',
      properties: {
        week_offset: {
          type: 'number',
          description: 'Week offset from current week (0 = this week, -1 = last week)'
        },
        format: {
          type: 'string',
          enum: ['json', 'text'],
          description: 'Output format (default: json)'
        }
      }
    },
  },

• src/utils.ts:253-294 (helper)

  Core utility function generateWeeklyReport that generates the structured weekly report from hydrated time entries, including daily breakdowns, project summaries, and workspace summaries.

  export function generateWeeklyReport(
    weekStart: Date,
    weekEnd: Date,
    entries: HydratedTimeEntry[]
  ): WeeklyReport {
    const totalSeconds = calculateTotalDuration(entries);
    
    // Group by date for daily breakdown
    const byDate = groupEntriesByDate(entries);
    const dailyBreakdown: DailyReport[] = [];
    byDate.forEach((dateEntries, date) => {
      dailyBreakdown.push(generateDailyReport(date, dateEntries));
    });
    
    // Sort daily reports
    dailyBreakdown.sort((a, b) => a.date.localeCompare(b.date));
    
    // Overall project summaries
    const byProject = groupEntriesByProject(entries);
    const projectSummaries: ProjectSummary[] = [];
    byProject.forEach((projectEntries, projectName) => {
      projectSummaries.push(generateProjectSummary(projectName, projectEntries));
    });
    
    // Overall workspace summaries
    const byWorkspace = groupEntriesByWorkspace(entries);
    const workspaceSummaries: WorkspaceSummary[] = [];
    byWorkspace.forEach((wsEntries, wsName) => {
      const wsId = wsEntries[0]?.workspace_id || 0;
      workspaceSummaries.push(generateWorkspaceSummary(wsName, wsId, wsEntries));
    });
    
    return {
      week_start: weekStart.toISOString().split('T')[0],
      week_end: weekEnd.toISOString().split('T')[0],
      total_hours: secondsToHours(totalSeconds),
      total_seconds: totalSeconds,
      daily_breakdown: dailyBreakdown,
      by_project: projectSummaries,
      by_workspace: workspaceSummaries
    };
  }

• src/utils.ts:297-330 (helper)

  Utility function formatReportForDisplay used by the handler to format the weekly report as human-readable text when format='text' is requested.

  export function formatReportForDisplay(report: DailyReport | WeeklyReport): string {
    const lines: string[] = [];
    
    if ('week_start' in report) {
      // Weekly report
      lines.push(`📊 Weekly Report (${report.week_start} to ${report.week_end})`);
      lines.push(`Total: ${report.total_hours} hours`);
      lines.push('');
      
      lines.push('📅 Daily Breakdown:');
      report.daily_breakdown.forEach(day => {
        lines.push(`  ${day.date}: ${day.total_hours}h`);
      });
    } else {
      // Daily report
      lines.push(`📊 Daily Report for ${report.date}`);
      lines.push(`Total: ${report.total_hours} hours`);
    }
    
    lines.push('');
    lines.push('🏢 By Workspace:');
    report.by_workspace.forEach(ws => {
      lines.push(`  ${ws.workspace_name}: ${ws.total_hours}h (${ws.project_count} projects)`);
    });
    
    lines.push('');
    lines.push('📁 By Project:');
    report.by_project.forEach(proj => {
      const client = proj.client_name ? ` (${proj.client_name})` : '';
      lines.push(`  ${proj.project_name}${client}: ${proj.total_hours}h`);
    });
    
    return lines.join('\n');
  }