Hub Planner MCP Server

Hub Planner

Hub Planner is a resource management and project scheduling platform for planning projects, allocating resources, tracking time, managing billing, and handling vacation/leave workflows.

Data Model

• Projects — Work containers with name, status (STATUS_ACTIVE/STATUS_ARCHIVED/STATUS_PENDING/ STATUS_PLANNED/STATUS_FLOATING), budget (hours + cash), timeline (start/end with useProjectDuration=true), assigned resources, project managers, tags, custom fields, and projectCode. Projects are what resources get booked against.

• Resources — People or assets with firstName, lastName, email, status (STATUS_ACTIVE/STATUS_ARCHIVED/STATUS_NON_BOOKABLE/STATUS_PARKED), role (ROLE_OWNER/ROLE_ADMIN/ROLE_MANAGER/ROLE_MEMBER), billing rates, custom availability, tags, and custom fields. Resources are allocated to projects via bookings.

• Bookings — The core scheduling unit. A booking allocates a resource to a project for a date range. Key fields: resource (ID), project (ID), start/end dates, state (STATE_PERCENTAGE / STATE_DAY_MINUTE / STATE_TOTAL_MINUTE), stateValue (the allocation amount), type (SCHEDULED / APPROVED / WAITING_FOR_APPROVAL / REJECTED), and optional booking category. Bookings default to 20 results per page — always paginate.

• Events — Non-project activities (conferences, training, company events). Events work like projects for booking purposes — resources can be booked against events using the booking tools with the event ID as the project_id. Events have name, eventCode, and backgroundColor.

• Time Entries — Timesheet records. Each entry logs minutes for a resource on a project for a specific date. Status flow: UNSUBMITTED → SUBMITTED → APPROVED/REJECTED. Time entries also default to 20 results per page.

• Milestones — Key dates within a project timeline. Each milestone has a name, date (YYYY-MM-DD), and project association. Use milestones to mark deliverables, deadlines, or phase gates. Milestones are queried via search (POST /milestone/search) — there is no GET-all endpoint.

• Vacations — Leave/time-off requests with an approval workflow. Each vacation has a resource, start/end dates, type (SCHEDULED/APPROVED/WAITING_FOR_APPROVAL/REJECTED), percentAllocation (100 = full day, 50 = half day), title, and approvalInfo containing approvers, notes, and approval/rejection details. Requires the Vacation extension.

• Holidays — Public/company holidays with name, date, optional yearly repeat, and color. Holidays affect resource availability calculations.

• Clients — Customer organizations that can be linked to projects via the customers array.

• Billing Rates — Rate cards with label, rate amount, and currency. Assigned to projects (projectRate) and resources (resourceRates) for budget tracking. Supports 20+ currencies.

• Project Tags / Resource Tags — Simple key-value labels for categorization. Project tags are assigned to projects, resource tags to resources (e.g. skills like "Python", "Design"). Each tag has a unique value. No pagination or search — the full list is returned.

• Booking Categories — Define booking types (e.g. At Client, Remote Work, Design, Development) with name, gridColor, and type (NON_OPTIONAL for default, CUSTOM for user-created). Categories belong to category groups. Used for categorizing and color-coding bookings on the scheduler.

• Custom Fields — Configurable fields on resources or projects. Templates define the field type (TEXT, TEXTAREA, EMAIL, DATE, COLOR, NUMBER, CHECKBOX, SELECT, RADIO), label, instructions, choices (for select/radio/checkbox), and settings (required, editable by resource, etc.). Values are stored on individual resources/projects via their customFields array.

• Project Groups / Resource Groups — Organizational containers. System groups (Active Projects, Archived Projects, Events) are auto-managed. Custom groups can be created for team/department structure. Each group has a name and array of member IDs.

• Project Managers — Resources with isProjectManager=true. A read-only view of resources eligible to manage projects. Assigned to projects via the project's managers field.

• Unassigned Work — Placeholder items for tasks/roles not yet assigned to a resource. Requires the Unassigned Work extension.

• Project Cost Categories — Expense categories (Accommodation, Flights, Equipment, etc.) for tracking project costs and budgets.

Key Relationships

• A booking connects one resource to one project (or event) for a date range
• Milestones belong to a project — each milestone references a project ID
• Time entries log actual hours: one resource, one project, one date, N minutes
• Vacations are per-resource with an approval workflow and optional approvers
• Billing rates are referenced by projects (projectRate) and resources (resourceRates)
• Clients are linked to projects via the customers array
• Tags are assigned to projects (project tags) or resources (resource tags)
• Booking categories classify individual bookings for filtering and reporting
• Custom field templates define fields; values live on resource/project objects
• Groups contain arrays of project or resource IDs

Common Workflows

1. Project setup: Create project → set budget/timeline → assign project managers → add tags
2. Resource allocation: Create booking (resource → project, date range, allocation %) → track on scheduler
3. Time tracking: Resource logs time entries (project, date, minutes) → submit → approve/reject
4. Capacity planning: List resources → check bookings → identify over/under-allocated → adjust
5. Leave management: Create vacation request (WAITING_FOR_APPROVAL) → approver reviews → approve/reject
6. Milestone tracking: Add milestones to project → monitor dates vs progress

Booking vs Event Distinction

Bookings are allocations (resource → project, with dates and effort). Events are a type of schedulable entity, similar to projects but for non-project activities. To schedule a resource for an event, create a booking with the event's ID as the project_id.

Pagination

Projects and resources return all results by default. Bookings, time entries, and vacations return 20 per page by default. Max limit is 1000. Use limit + page params. Pages start at 0.

Sorting

Most list endpoints support a sort parameter. Field name for ascending, prefix with - for descending: sort=name (A-Z), sort=-createdDate (newest first). Chain: sort=-status&sort=name.

Update Patterns

Different entities use different update approaches:

• Projects and resources: PATCH with array of objects — partial updates
• Bookings: PATCH with partial data on single object
• Events, time entries, holidays, billing rates, milestones: GET → merge → PUT (full object)
• Vacations: PATCH with partial data (preferred over PUT)
• Tags: PUT with just the new value
• Clients: PUT with the updated fields

API Rate Limits

6000 calls/day, burst limit of 50 per 5 seconds. Rate limit headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset. Exceeding burst limit returns Retry-After header.

API Quirks

• Milestone listing uses POST /milestone/search (no GET-all endpoint)
• Tag values must be unique per type — creating a duplicate returns TAG_VALUE_EXIST error
• Vacation approval requires either default approvers on the resource or explicit approver IDs
• Booking category deletion is not supported via API
• Custom field values are stored on resource/project objects, not on the template
• Project/resource status values are prefixed: STATUS_ACTIVE, STATUS_ARCHIVED, etc.