get_public_holidays

Retrieve public holidays for any year from 2000 to 2100 with daily details and total count calculations.

Instructions

Get all public holidays for a specific year with daily breakdown and total calculations

Input Schema

TableJSON Schema

Name	Required	Description	Default
`year`	Yes	Year to retrieve public holidays for (e.g., 2024)

Implementation Reference

src/tools/publicHolidaysTools.ts:20-53 (handler)

The complete tool definition for 'get_public_holidays' including the handler function that validates input, fetches data from Moco API, handles empty results and errors, and formats the output.

export const getPublicHolidaysTool = {
  name: 'get_public_holidays',
  description: 'Get all public holidays for a specific year with daily breakdown and total calculations',
  inputSchema: zodToJsonSchema(GetPublicHolidaysSchema),
  handler: async (params: z.infer<typeof GetPublicHolidaysSchema>): Promise<string> => {
    const { year } = params;

    // Validate year parameter
    if (!Number.isInteger(year) || year < 2000 || year > 2100) {
      return createValidationErrorMessage({
        field: 'year',
        value: year,
        reason: 'invalid_year_range'
      });
    }

    try {
      const apiService = new MocoApiService();
      const publicHolidays = await apiService.getPublicHolidays(year);

      if (publicHolidays.length === 0) {
        return createEmptyResultMessage({
          type: 'public_holidays',
          year
        });
      }

      return formatPublicHolidaysSummary(publicHolidays, year);

    } catch (error) {
      return `Error retrieving public holidays for ${year}: ${error instanceof Error ? error.message : 'Unknown error'}`;
    }
  }
};

src/tools/publicHolidaysTools.ts:11-14 (schema)

Zod schema defining the input for the get_public_holidays tool: a year parameter between 2000 and 2100.

// Schema for get_public_holidays tool
const GetPublicHolidaysSchema = z.object({
  year: z.number().int().min(2000).max(2100).describe('Year to retrieve public holidays for (e.g., 2024)')
});

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

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

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

src/services/mocoApi.ts:328-352 (helper)

MocoApiService method that fetches all schedules for the year and filters for public holidays (assignment code '2'). Called by the tool handler.

async getPublicHolidays(year: number): Promise<any[]> {
  // Calculate year date range
  const startDate = `${year}-01-01`;
  const endDate = `${year}-12-31`;
  
  try {
    // Get ALL schedules using direct request
    const allSchedules = await this.makeRequest<any[]>('/schedules', {
      from: startDate,
      to: endDate
    });
    
    // Filter for public holidays (assignment code "2" and type "Absence")
    const publicHolidays = allSchedules.filter(schedule => 
      schedule.assignment && 
      schedule.assignment.type === 'Absence' &&
      schedule.assignment.code === '2'
    );
    
    return publicHolidays;
  } catch (error) {
    console.error('DEBUG API: Error fetching public holidays:', error);
    return [];
  }
}

src/tools/publicHolidaysTools.ts:58-89 (helper)

Helper function called by the handler to format the public holidays data into a readable summary with dates, totals, and approximate working days calculation.

function formatPublicHolidaysSummary(holidays: any[], year: number): string {
  const lines: string[] = [];
  
  lines.push(`Public holidays for ${year}:`);
  lines.push('');

  if (holidays.length > 0) {
    // Sort holidays by date
    const sortedHolidays = holidays.sort((a, b) => a.date.localeCompare(b.date));
    
    lines.push('Holiday dates:');
    sortedHolidays.forEach(holiday => {
      const holidayName = holiday.assignment?.name || 'Public Holiday';
      const date = holiday.date;
      lines.push(`- ${date}: ${holidayName}`);
    });
    lines.push('');
  }

  // Summary statistics
  lines.push('Summary:');
  lines.push(`- Total public holidays: ${holidays.length} days`);
  
  // Calculate remaining working days (rough estimate: 365 - weekends - holidays)
  const totalDaysInYear = isLeapYear(year) ? 366 : 365;
  const approximateWeekends = Math.floor(totalDaysInYear / 7) * 2;
  const approximateWorkingDays = totalDaysInYear - approximateWeekends - holidays.length;
  
  lines.push(`- Approximate working days: ${approximateWorkingDays} days`);

  return lines.join('\\n');
}

MoCo MCP Server