get_holiday_stats

Retrieve Taiwan holiday statistics for a specific year or month to analyze holiday distribution and plan schedules effectively.

Instructions

獲取指定年份或年月的台灣假期統計資訊

Input Schema

TableJSON Schema

Name	Required	Description	Default
`year`	Yes	要查詢的年份
`month`	No	要查詢的月份（可選），1-12

Implementation Reference

src/holiday-service.ts:254-276 (handler)

Core handler function that implements the get_holiday_stats tool logic: fetches holidays for the specified year, optionally filters by month, validates input, and delegates to calculateStats.

async getHolidayStats(year: number, month?: number): Promise<HolidayStats> {
  const holidays = await this.getHolidaysForYear(year);
  
  let filteredHolidays = holidays;
  
  // 如果指定月份，進行篩選
  if (month !== undefined) {
    if (month < 1 || month > 12) {
      throw new HolidayServiceError(
        `無效的月份: ${month}，月份必須在 1-12 之間`,
        ErrorType.INVALID_MONTH
      );
    }
    
    const monthStr = month.toString().padStart(2, '0');
    filteredHolidays = holidays.filter(holiday => {
      const holidayMonth = holiday.date.substring(4, 6);
      return holidayMonth === monthStr;
    });
  }

  return this.calculateStats(year, filteredHolidays);
}

src/server.ts:565-594 (handler)

MCP server handler for the get_holiday_stats tool: validates arguments, calls HolidayService.getHolidayStats, and formats the JSON response.

private async handleGetHolidayStats(args: any) {
  const { year, month } = args;
  
  if (!year || typeof year !== 'number') {
    throw new Error('缺少必要參數：year');
  }

  const stats = await this.holidayService.getHolidayStats(year, month);
  
  return {
    content: [
      {
        type: 'text',
        text: JSON.stringify({
          success: true,
          data: {
            year: year,
            month: month,
            statistics: stats,
            summary: month 
              ? `${year} 年 ${month} 月共有 ${stats.totalHolidays} 個假期`
              : `${year} 年共有 ${stats.totalHolidays} 個假期`
          },
          timestamp: new Date().toISOString(),
          tool: 'get_holiday_stats'
        }, null, 2),
      },
    ],
  };
}

src/server.ts:112-134 (registration)

Tool registration in ListToolsRequestSchema handler: defines name, description, and input schema for get_holiday_stats.

{
  name: 'get_holiday_stats',
  description: '獲取指定年份或年月的台灣假期統計資訊',
  inputSchema: {
    type: 'object',
    properties: {
      year: {
        type: 'integer',
        description: '要查詢的年份',
        minimum: 2017,
        maximum: 2026
      },
      month: {
        type: 'integer',
        description: '要查詢的月份（可選），1-12',
        minimum: 1,
        maximum: 12
      }
    },
    required: ['year'],
    additionalProperties: false,
  },
} as Tool,

src/types.ts:33-48 (schema)

Type definition for HolidayStats, the return type of the get_holiday_stats tool.

export interface HolidayStats {
  /** 年份 */
  year: number;
  /** 總假日天數 */
  totalHolidays: number;
  /** 國定假日天數 */
  nationalHolidays: number;
  /** 補假天數 */
  compensatoryDays: number;
  /** 調整放假天數 */
  adjustedHolidays: number;
  /** 補班天數 */
  workingDays: number;
  /** 假日類型分布 */
  holidayTypes: Record<string, number>;
}

src/holiday-service.ts:456-501 (helper)

Helper function that processes holiday data to compute detailed statistics by type and category.

private calculateStats(year: number, holidays: Holiday[]): HolidayStats {
  const holidayTypes: Record<string, number> = {};
  let totalHolidays = 0;
  let nationalHolidays = 0;
  let compensatoryDays = 0;
  let adjustedHolidays = 0;
  let workingDays = 0;

  for (const holiday of holidays) {
    if (holiday.isHoliday) {
      totalHolidays++;
      
      // 分析假日類型
      const description = holiday.description.toLowerCase();
      
      if (description.includes('補假')) {
        compensatoryDays++;
        holidayTypes[HOLIDAY_TYPES.COMPENSATORY] = (holidayTypes[HOLIDAY_TYPES.COMPENSATORY] || 0) + 1;
      } else if (description.includes('調整放假')) {
        adjustedHolidays++;
        holidayTypes[HOLIDAY_TYPES.ADJUSTED] = (holidayTypes[HOLIDAY_TYPES.ADJUSTED] || 0) + 1;
      } else {
        nationalHolidays++;
        holidayTypes[HOLIDAY_TYPES.NATIONAL] = (holidayTypes[HOLIDAY_TYPES.NATIONAL] || 0) + 1;
      }
      
      // 記錄具體假日類型
      if (holiday.description) {
        holidayTypes[holiday.description] = (holidayTypes[holiday.description] || 0) + 1;
      }
    } else if (holiday.description.includes('補行上班')) {
      workingDays++;
      holidayTypes[HOLIDAY_TYPES.WORKING] = (holidayTypes[HOLIDAY_TYPES.WORKING] || 0) + 1;
    }
  }

  return {
    year,
    totalHolidays,
    nationalHolidays,
    compensatoryDays,
    adjustedHolidays,
    workingDays,
    holidayTypes
  };
}

Taiwan Holiday MCP Server