MCP Toggl Server

Instructions

Implementation Reference

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

  Main handler for the toggl_weekly_report tool. Ensures cache is warmed, fetches and hydrates time entries for the week, calculates week boundaries, generates the report using helper functions, and returns formatted or JSON output.
  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)

  Tool schema definition including name, description, and inputSchema for parameters 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)

  Key helper function that processes hydrated time entries into a structured WeeklyReport, 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/toggl-api.ts:245-259 (helper)

  TogglAPI helper method to fetch time entries specifically for a given week offset by calculating the Monday-to-Sunday date range and querying the API.
  async getTimeEntriesForWeek(weekOffset = 0): Promise<TimeEntry[]> { const today = new Date(); const dayOfWeek = today.getDay(); const diff = today.getDate() - dayOfWeek + (dayOfWeek === 0 ? -6 : 1); // Adjust for Sunday const monday = new Date(today.setDate(diff)); monday.setDate(monday.getDate() + (weekOffset * 7)); monday.setHours(0, 0, 0, 0); const sunday = new Date(monday); sunday.setDate(sunday.getDate() + 6); sunday.setHours(23, 59, 59, 999); return this.getTimeEntriesForDateRange(monday, sunday); }