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