MoCo MCP Server

Instructions

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');
  }