Taiwan Holiday MCP Server

Instructions

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