create-public-holiday

Instructions

Implementation Reference

• src/tools/time-management/public-holidays.ts:52-71 (handler)

  The handler function that executes the create-public-holiday tool logic. It accepts name, date, and optional fields (region, country, type, moveable, recurring, year, notes, active) as input, then posts to the Float API /public-holidays endpoint and returns the created holiday validated against publicHolidaySchema.

  export const createPublicHoliday = createTool(
    'create-public-holiday',
    'Create a new public holiday',
    z.object({
      name: z.string().describe('Holiday name'),
      date: z.string().describe('Holiday date (YYYY-MM-DD)'),
      region: z.string().optional().describe('Region or country code'),
      country: z.string().optional().describe('Country name'),
      type: z.string().optional().describe('Holiday type (bank_holiday, observed, etc.)'),
      moveable: z.number().optional().describe('Moveable status (0=fixed, 1=moveable)'),
      recurring: z.number().optional().describe('Recurring status (0=one-time, 1=recurring)'),
      year: z.number().optional().describe('Year for the holiday'),
      notes: z.string().optional().describe('Additional notes'),
      active: z.number().optional().describe('Active status (1=active, 0=archived)'),
    }),
    async (params) => {
      const holiday = await floatApi.post('/public-holidays', params, publicHolidaySchema);
      return holiday;
    }
  );

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

  Zod schema defining the public holiday response shape. Used to validate the response from Float API when creating (or reading) a public holiday.

  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:175-323 (registration)

  The createPublicHoliday tool is registered in the legacyTools array (line 288) and exported via the tools and allTools arrays for use by the MCP server.

  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];
  
  // Alternative export that includes both optimized and legacy tools
  export const allTools = [...optimizedTools, ...legacyTools];

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

  The createTool helper factory function that wraps a name, description, input schema, and handler into a standardized tool object with error handling and response formatting.

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