MCP Toggl Server

Instructions

Implementation Reference

• src/index.ts:617-659 (handler)

  Main handler logic for the 'toggl_project_summary' tool. Fetches time entries based on input parameters, hydrates them using cache, groups by project using helper, generates summaries, sorts by total hours descending, and returns formatted JSON response.

  case 'toggl_project_summary': {
    await ensureCache();
    
    let entries: TimeEntry[];
    
    if (args?.period) {
      const range = getDateRange(args.period as any);
      entries = await api.getTimeEntriesForDateRange(range.start, range.end);
    } else if (args?.start_date && args?.end_date) {
      const start = new Date(args.start_date as string);
      const end = new Date(args.end_date as string);
      entries = await api.getTimeEntriesForDateRange(start, end);
    } else {
      // Default to current week
      entries = await api.getTimeEntriesForWeek(0);
    }
    
    if (args?.workspace_id) {
      entries = entries.filter(e => e.workspace_id === args.workspace_id);
    }
    
    const hydrated = await cache.hydrateTimeEntries(entries);
    const byProject = groupEntriesByProject(hydrated);
    
    const summaries: any[] = [];
    byProject.forEach((projectEntries, projectName) => {
      summaries.push(generateProjectSummary(projectName, projectEntries));
    });
    
    // Sort by total hours descending
    summaries.sort((a, b) => b.total_seconds - a.total_seconds);
    
    return {
      content: [{
        type: 'text',
        text: JSON.stringify({ 
          project_count: summaries.length,
          total_hours: secondsToHours(summaries.reduce((t, s) => t + s.total_seconds, 0)),
          projects: summaries 
        }, null, 2)
      }]
    };
  }

• src/index.ts:265-290 (schema)

  Tool schema definition including name, description, and input schema for parameters like period, start_date, end_date, and workspace_id.

  {
    name: 'toggl_project_summary',
    description: 'Get total hours per project for a date range',
    inputSchema: {
      type: 'object',
      properties: {
        period: {
          type: 'string',
          enum: ['week', 'lastWeek', 'month', 'lastMonth'],
          description: 'Predefined period'
        },
        start_date: {
          type: 'string',
          description: 'Start date (YYYY-MM-DD format)'
        },
        end_date: {
          type: 'string',
          description: 'End date (YYYY-MM-DD format)'
        },
        workspace_id: {
          type: 'number',
          description: 'Filter by workspace ID'
        }
      }
    },
  },

• src/utils.ts:111-124 (helper)

  Helper function to group hydrated time entries by project name, used in project summary generation.

  // Group time entries by project
  export function groupEntriesByProject(entries: HydratedTimeEntry[]): Map<string, HydratedTimeEntry[]> {
    const grouped = new Map<string, HydratedTimeEntry[]>();
    
    entries.forEach(entry => {
      const key = entry.project_name || 'No Project';
      if (!grouped.has(key)) {
        grouped.set(key, []);
      }
      grouped.get(key)!.push(entry);
    });
    
    return grouped;
  }

• src/utils.ts:174-195 (helper)

  Core helper function that generates a ProjectSummary object from project name and entries, calculating total and billable hours.

  // Generate project summary
  export function generateProjectSummary(
    projectName: string,
    entries: HydratedTimeEntry[]
  ): ProjectSummary {
    const totalSeconds = calculateTotalDuration(entries);
    const billableSeconds = entries
      .filter(e => e.billable)
      .reduce((total, e) => total + (e.duration < 0 ? 0 : e.duration), 0);
    
    return {
      project_id: entries[0]?.project_id,
      project_name: projectName,
      client_name: entries[0]?.client_name,
      workspace_name: entries[0]?.workspace_name || 'Unknown',
      total_hours: secondsToHours(totalSeconds),
      total_seconds: totalSeconds,
      billable_hours: secondsToHours(billableSeconds),
      billable_seconds: billableSeconds,
      entry_count: entries.length
    };
  }

• src/utils.ts:11-14 (helper)

  Utility function to convert total seconds to decimal hours, used in summaries.

  // Convert seconds to hours with decimal precision
  export function secondsToHours(seconds: number): number {
    return Math.round((seconds / 3600) * 100) / 100;
  }