get-public-holiday

Instructions

Implementation Reference

• src/tools/time-management/public-holidays.ts:35-49 (handler)

  The handler function for the 'get-public-holiday' tool. It calls floatApi.get with the holiday ID and validates the response against publicHolidaySchema.

  // Get public holiday details
  export const getPublicHoliday = createTool(
    'get-public-holiday',
    'Get detailed information about a specific public holiday',
    z.object({
      holiday_id: z.union([z.string(), z.number()]).describe('The public holiday ID'),
    }),
    async (params) => {
      const holiday = await floatApi.get(
        `/public-holidays/${params.holiday_id}`,
        publicHolidaySchema
      );
      return holiday;
    }
  );

• src/types/float.ts:369-383 (schema)

  The Zod schema (publicHolidaySchema) that validates the public holiday data returned by the API.

  export const publicHolidaySchema = z.object({
    holiday_id: z.union([z.string(), z.number()]).optional(), // Float API uses holiday_id
    name: z.string(),
    date: z.string(), // ISO date format (YYYY-MM-DD)
    region: z.string().nullable().optional(), // Region or country code
    country: z.string().nullable().optional(), // Country name
    type: z.string().nullable().optional(), // Holiday type (bank_holiday, observed, etc.)
    active: z.number().nullable().optional(), // 0 = archived, 1 = active
    created: z.string().nullable().optional(), // Float API uses 'created', not 'created_at'
    modified: z.string().nullable().optional(), // Float API uses 'modified', not 'updated_at'
    moveable: z.number().nullable().optional(), // 0 = fixed date, 1 = moveable
    year: z.number().nullable().optional(), // Year for the holiday
    recurring: z.number().nullable().optional(), // 0 = one-time, 1 = recurring
    notes: z.string().nullable().optional(), // Additional notes
  });

• src/tools/index.ts:137-319 (registration)

  The 'getPublicHoliday' tool is imported from public-holidays.ts and registered in the legacyTools array (line 287) for use by the MCP server.

    listPublicHolidays,
    getPublicHoliday,
    createPublicHoliday,
    updatePublicHoliday,
    deletePublicHoliday,
  } from './time-management/public-holidays.js';
  import {
    listTeamHolidays,
    getTeamHoliday,
    createTeamHoliday,
    updateTeamHoliday,
    deleteTeamHoliday,
    listTeamHolidaysByDepartment,
    listTeamHolidaysByDateRange,
    listRecurringTeamHolidays,
    getUpcomingTeamHolidays,
  } from './time-management/team-holidays.js';
  import {
    listLoggedTime,
    getLoggedTime,
    createLoggedTime,
    updateLoggedTime,
    deleteLoggedTime,
    bulkCreateLoggedTime,
    getPersonLoggedTimeSummary,
    getProjectLoggedTimeSummary,
    getLoggedTimeTimesheet,
    getBillableTimeReport,
  } from './time-management/logged-time.js';
  
  // Reporting tools
  import {
    getTimeReport,
    getProjectReport,
    getPeopleUtilizationReport,
  } from './reporting/reports.js';
  
  // Legacy tools export (preserved for backward compatibility)
  export const legacyTools = [
    // Core entity tools
    listPeople,
    getPerson,
    createPerson,
    updatePerson,
    deletePerson,
    listDepartments,
    getDepartment,
    createDepartment,
    updateDepartment,
    deleteDepartment,
    listStatuses,
    getStatus,
    createStatus,
    updateStatus,
    deleteStatus,
    getDefaultStatus,
    setDefaultStatus,
    getStatusesByType,
    listRoles,
    getRole,
    createRole,
    updateRole,
    deleteRole,
    getRolesByPermission,
    getRolePermissions,
    updateRolePermissions,
    getRoleHierarchy,
    checkRoleAccess,
    listAccounts,
    getAccount,
    updateAccount,
    manageAccountPermissions,
    createAccount,
    deactivateAccount,
    reactivateAccount,
    getCurrentAccount,
    updateAccountTimezone,
    setAccountDepartmentFilter,
    bulkUpdateAccountPermissions,
  
    // Project management tools
    listProjects,
    getProject,
    createProject,
    updateProject,
    deleteProject,
    listTasks,
    getTask,
    createTask,
    updateTask,
    deleteTask,
    listClients,
    getClient,
    createClient,
    updateClient,
    deleteClient,
    listAllocations,
    getAllocation,
    createAllocation,
    updateAllocation,
    deleteAllocation,
    listMilestones,
    getMilestone,
    createMilestone,
    updateMilestone,
    deleteMilestone,
    getProjectMilestones,
    getUpcomingMilestones,
    getOverdueMilestones,
    completeMilestone,
    getMilestoneReminders,
    listPhases,
    getPhase,
    createPhase,
    updatePhase,
    deletePhase,
    listPhasesByProject,
    getPhasesByDateRange,
    getActivePhases,
    getPhaseSchedule,
    listProjectTasks,
    getProjectTask,
    createProjectTask,
    updateProjectTask,
    deleteProjectTask,
    getProjectTasksByProject,
    getProjectTasksByPhase,
    bulkCreateProjectTasks,
    reorderProjectTasks,
    archiveProjectTask,
    getProjectTaskDependencies,
  
    // Time management tools
    listTimeOff,
    getTimeOff,
    createTimeOff,
    updateTimeOff,
    deleteTimeOff,
    bulkCreateTimeOff,
    approveTimeOff,
    rejectTimeOff,
    listTimeOffTypes,
    getTimeOffCalendar,
    getPersonTimeOffSummary,
    listTimeOffTypesConfig,
    getTimeOffType,
    createTimeOffType,
    updateTimeOffType,
    deleteTimeOffType,
    listPublicHolidays,
    getPublicHoliday,
    createPublicHoliday,
    updatePublicHoliday,
    deletePublicHoliday,
    listTeamHolidays,
    getTeamHoliday,
    createTeamHoliday,
    updateTeamHoliday,
    deleteTeamHoliday,
    listTeamHolidaysByDepartment,
    listTeamHolidaysByDateRange,
    listRecurringTeamHolidays,
    getUpcomingTeamHolidays,
    listLoggedTime,
    getLoggedTime,
    createLoggedTime,
    updateLoggedTime,
    deleteLoggedTime,
    bulkCreateLoggedTime,
    getPersonLoggedTimeSummary,
    getProjectLoggedTimeSummary,
    getLoggedTimeTimesheet,
    getBillableTimeReport,
  
    // Reporting tools
    getTimeReport,
    getProjectReport,
    getPeopleUtilizationReport,
  ];
  
  // Primary export: Optimized tools (4 consolidated tools replacing 246+ granular tools)
  // Also includes legacy tools for backward compatibility with existing tests
  export const tools = [...optimizedTools, ...legacyTools];

• src/tools/base.ts:50-104 (helper)

  The createTool factory function that wraps the handler with schema validation and error handling.

  export const createTool = <T, P extends z.ZodType>(
    name: string,
    description: string,
    schema: P,
    handler: (params: z.infer<P>) => Promise<T>
  ): {
    name: string;
    description: string;
    inputSchema: P;
    handler: (params: unknown) => Promise<ToolResponse<T>>;
  } => {
    return {
      name,
      description,
      inputSchema: schema,
      handler: async (params: unknown): Promise<ToolResponse<T>> => {
        try {
          const validatedParams = schema.parse(params);
          const result = await handler(validatedParams);
  
          // Extract format from params if available
          const responseFormat =
            ((validatedParams as Record<string, unknown>).format as ResponseFormat) || 'json';
  
          return { success: true, data: result, format: responseFormat };
        } catch (error) {
          logger.error(`Error in ${name} tool:`, error);
  
          // Handle Float API errors with enhanced formatting
          if (error instanceof FloatApiError) {
            return FloatErrorHandler.formatErrorForMcp(error) as ToolResponse<T>;
          }
  
          // Handle parameter validation errors
          if (error instanceof z.ZodError) {
            return {
              success: false,
              error: `Parameter validation failed: ${error.errors.map((e) => `${e.path.join('.')}: ${e.message}`).join(', ')}`,
              errorCode: 'PARAMETER_VALIDATION_ERROR',
              details: {
                validationErrors: error.errors,
              },
            } as ToolResponse<T>;
          }
  
          // Handle other errors
          return {
            success: false,
            error: error instanceof Error ? error.message : 'Unknown error occurred',
            errorCode: 'UNKNOWN_ERROR',
          } as ToolResponse<T>;
        }
      },
    };
  };

• src/services/float-api.ts:630-634 (helper)

  The floatApi.get method used by the handler to make GET requests to the Float API.

  async get<T>(url: string, schema?: z.ZodType<T>, format: ResponseFormat = 'json'): Promise<T> {
    return this.handleRateLimitRetry(() =>
      this.makeRequest<T>('GET', url, undefined, schema, format)
    );
  }