toggl_weekly_report
Generate weekly time tracking reports with daily breakdowns and project summaries from Toggl Track data. Specify week offset and output format for structured reporting.
Instructions
Generate a weekly report with daily breakdown and project summaries
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| week_offset | No | Week offset from current week (0 = this week, -1 = last week) | |
| format | No | Output format (default: json) |
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'); }