MoCo MCP Server

Instructions

Implementation Reference

• src/tools/userPresencesTools.ts:24-59 (handler)

  Main tool handler for 'get_user_presences': validates dates, fetches presences via API, aggregates by day, calculates totals and formats output as a readable summary with statistics.

  export const getUserPresencesTool = {
    name: 'get_user_presences',
    description: 'Get user presences within a date range with daily aggregation and total calculations',
    inputSchema: zodToJsonSchema(GetUserPresencesSchema),
    handler: async (params: z.infer<typeof GetUserPresencesSchema>): Promise<string> => {
      const { startDate, endDate } = params;
  
      // Validate date format and range
      if (!validateDateRange(startDate, endDate)) {
        return createValidationErrorMessage({
          field: 'dateRange',
          value: `${startDate} to ${endDate}`,
          reason: 'invalid_date_range'
        });
      }
  
      try {
        const apiService = new MocoApiService();
        const presences = await apiService.getUserPresences(startDate, endDate);
  
        if (presences.length === 0) {
          return createEmptyResultMessage({
            type: 'presences',
            startDate,
            endDate
          });
        }
  
        const summary = aggregatePresences(presences, startDate, endDate);
        return formatPresencesSummary(summary);
  
      } catch (error) {
        return `Error retrieving presences: ${error instanceof Error ? error.message : 'Unknown error'}`;
      }
    }
  };

• src/tools/userPresencesTools.ts:15-18 (schema)

  Zod schema defining input parameters: startDate and endDate as ISO date strings.

  const GetUserPresencesSchema = z.object({
    startDate: z.string().describe('Start date in ISO 8601 format (YYYY-MM-DD)'),
    endDate: z.string().describe('End date in ISO 8601 format (YYYY-MM-DD)')
  });

• src/index.ts:34-42 (registration)

  Registration of getUserPresencesTool in the AVAILABLE_TOOLS array used by MCP server for tool listing and execution dispatching.

  const AVAILABLE_TOOLS = [
    getActivitiesTool,
    getUserProjectsTool,
    getUserProjectTasksTool,
    getUserHolidaysTool,
    getUserPresencesTool,
    getUserSickDaysTool,
    getPublicHolidaysTool
  ];

• src/services/mocoApi.ts:360-365 (helper)

  MocoApiService method to fetch raw user presences data from MoCo API endpoint '/users/presences' with automatic pagination.

  async getUserPresences(startDate: string, endDate: string): Promise<UserPresence[]> {
    return this.fetchAllPages<UserPresence>('/users/presences', {
      from: startDate,
      to: endDate
    });
  }

• src/tools/userPresencesTools.ts:64-96 (helper)

  Helper function to aggregate presences: groups by date, creates daily summaries with total hours, sorts dates and computes grand total.

  function aggregatePresences(presences: UserPresence[], startDate: string, endDate: string): PresenceRangeSummary {
    // Group presences by date and calculate daily totals
    const presencesByDate = new Map<string, UserPresence[]>();
    
    presences.forEach(presence => {
      if (!presencesByDate.has(presence.date)) {
        presencesByDate.set(presence.date, []);
      }
      presencesByDate.get(presence.date)!.push(presence);
    });
  
    // Create daily summaries
    const dailySummaries: DailyPresenceSummary[] = [];
    
    // Sort dates for consistent output
    const sortedDates = Array.from(presencesByDate.keys()).sort();
    
    sortedDates.forEach(date => {
      const dayPresences = presencesByDate.get(date)!;
      const dailySummary = createDailyPresenceSummary(date, dayPresences);
      dailySummaries.push(dailySummary);
    });
  
    // Calculate grand total
    const grandTotalHours = sumHours(dailySummaries.map(day => day.totalHours));
  
    return {
      startDate,
      endDate,
      dailySummaries,
      grandTotal: createTimeFormat(grandTotalHours)
    };
  }