Taiwan Holiday MCP Server

Instructions

Implementation Reference

• src/server.ts:525-560 (handler)

  Handler for executing the get_holidays_in_range tool. Validates parameters, fetches holidays using HolidayService, filters actual holidays (isHoliday: true), and returns formatted JSON response.

  private async handleGetHolidaysInRange(args: any) {
    const { start_date, end_date } = args;
    
    if (!start_date || typeof start_date !== 'string') {
      throw new Error('缺少必要參數：start_date');
    }
    
    if (!end_date || typeof end_date !== 'string') {
      throw new Error('缺少必要參數：end_date');
    }
  
    const holidays = await this.holidayService.getHolidaysInRange(start_date, end_date);
    
    // 只返回實際的假期（isHoliday: true）
    const actualHolidays = holidays.filter(h => h.isHoliday);
    
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify({
            success: true,
            data: {
              startDate: start_date,
              endDate: end_date,
              holidays: actualHolidays,
              totalCount: actualHolidays.length,
              summary: `在 ${start_date} 到 ${end_date} 期間共有 ${actualHolidays.length} 個假期`
            },
            timestamp: new Date().toISOString(),
            tool: 'get_holidays_in_range'
          }, null, 2),
        },
      ],
    };
  }

• src/server.ts:92-111 (schema)

  Tool schema definition in ListTools response, including name, description, and input schema with validation for start_date and end_date parameters.

    name: 'get_holidays_in_range',
    description: '獲取指定日期範圍內的所有台灣假期',
    inputSchema: {
      type: 'object',
      properties: {
        start_date: {
          type: 'string',
          description: '開始日期，支援格式：YYYY-MM-DD 或 YYYYMMDD',
          pattern: '^(\\d{4}-\\d{2}-\\d{2}|\\d{8})$'
        },
        end_date: {
          type: 'string',
          description: '結束日期，支援格式：YYYY-MM-DD 或 YYYYMMDD',
          pattern: '^(\\d{4}-\\d{2}-\\d{2}|\\d{8})$'
        }
      },
      required: ['start_date', 'end_date'],
      additionalProperties: false,
    },
  } as Tool,

• src/holiday-service.ts:206-249 (helper)

  Core implementation that parses start and end dates, validates range, fetches holidays for each year in range using getHolidaysForYear, filters those within range using isDateInRange, sorts by date, and handles errors.

  async getHolidaysInRange(startDate: string, endDate: string): Promise<Holiday[]> {
    try {
      const start = parseDate(startDate);
      const end = parseDate(endDate);
      
      // 驗證日期範圍
      if (start.year > end.year || 
          (start.year === end.year && start.month > end.month) ||
          (start.year === end.year && start.month === end.month && start.day > end.day)) {
        throw new HolidayServiceError(
          `開始日期 ${startDate} 不能晚於結束日期 ${endDate}`,
          ErrorType.INVALID_DATE
        );
      }
  
      const result: Holiday[] = [];
      
      // 處理跨年度的情況
      for (let year = start.year; year <= end.year; year++) {
        const holidays = await this.getHolidaysForYear(year);
        
        for (const holiday of holidays) {
          const holidayDate = parseDate(holiday.date);
          
          // 檢查是否在範圍內
          if (this.isDateInRange(holidayDate, start, end)) {
            result.push(holiday);
          }
        }
      }
      
      // 按日期排序
      return result.sort((a, b) => a.date.localeCompare(b.date));
    } catch (error) {
      if (error instanceof DateParseError) {
        throw new HolidayServiceError(
          `日期解析錯誤: ${error.message}`,
          error.type,
          error
        );
      }
      throw error;
    }
  }

• src/server.ts:148-149 (registration)

  Dispatch registration in the CallToolRequestSchema switch statement that routes to the specific handler.

  case 'get_holidays_in_range':
    return await this.handleGetHolidaysInRange(args);