get_holiday_stats
Retrieve detailed statistics for Taiwan holidays for a specific year or month using the Taiwan Holiday MCP Server. Input the year and optional month to access accurate holiday data.
Instructions
獲取指定年份或年月的台灣假期統計資訊
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| month | No | 要查詢的月份（可選），1-12 | |
| year | Yes | 要查詢的年份 |
Implementation Reference
- src/server.ts:565-594 (handler)The MCP tool handler function that executes get_holiday_stats: validates input, calls HolidayService.getHolidayStats, and returns formatted 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:92-134 (registration)Registers the get_holiday_stats tool in the ListToolsRequestHandler, including name, description, and input schema.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, { 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/server.ts:115-133 (schema)Input schema definition for the get_holiday_stats tool, specifying year (required) and optional month parameters with validation.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, },
- src/holiday-service.ts:254-276 (helper)Core helper method in HolidayService that fetches holidays for the year, optionally filters by month, and computes HolidayStats.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/holiday-service.ts:456-501 (helper)Private helper method that calculates detailed holiday statistics from a list of holidays, categorizing by type and counting various metrics.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 }; }