@goodsamsoftware/freshbooks-mcp 1.0.6 → 1.0.7

package/dist/tools/time-entry/timeentry-create.js

@@ -11,55 +11,55 @@ import { logger } from '../../utils/logger.js';
  */
 export const timeentryCreateTool = {
     name: 'timeentry_create',
-    description: `Create a new time entry in FreshBooks.
-
-WHEN TO USE:
-- User says "log my time", "track time", "record hours", "add time entry"
-- User mentions working on a project with duration
-- User wants to record billable or non-billable time
-- User asks "log 2 hours on project X", "track 45 minutes of work"
-
-REQUIRED:
-- businessId: FreshBooks business ID (get from user_me -> businessMemberships[].business.id)
-- duration: Time in seconds (or ask user for hours/minutes and convert)
-  * 1 hour = 3600 seconds
-  * 1 minute = 60 seconds
-  * Example: 2 hours 30 minutes = 9000 seconds
-
-OPTIONAL BUT RECOMMENDED:
-- note: Description of work performed (improves billing accuracy)
-- projectId: Associate with a project
-- clientId: Associate with a client
-- serviceId: Service type for billing categorization
-- taskId: Associate with a task
-- billable: Whether time is billable (default: true if isLogged=true)
-- startedAt: When work began (ISO 8601 format, defaults to now)
-- isLogged: Whether time is logged (default: true)
-  * Set to false for active timers (with duration=0 and active=true)
-
-SPECIAL CASES:
-- To start a timer: Set duration=0, active=true, isLogged=false
-- For completed work: Set duration to actual seconds, isLogged=true
-
-RETURNS:
-Created time entry with:
-- id: New time entry ID (save this for updates/deletes)
-- duration: Confirmed duration in seconds
-- All other time entry fields
-
-EXAMPLES:
-User says: "Log 2 hours on Project Alpha for code review"
-→ duration: 7200 (2 * 3600)
-→ note: "code review"
-→ projectId: (look up Project Alpha)
-
-User says: "Track 45 minutes of meeting time"
-→ duration: 2700 (45 * 60)
-→ note: "meeting"
-
-User says: "Record 3 hours of development work for client ABC"
-→ duration: 10800 (3 * 3600)
-→ note: "development work"
+    description: `Create a new time entry in FreshBooks.
+
+WHEN TO USE:
+- User says "log my time", "track time", "record hours", "add time entry"
+- User mentions working on a project with duration
+- User wants to record billable or non-billable time
+- User asks "log 2 hours on project X", "track 45 minutes of work"
+
+REQUIRED:
+- businessId: FreshBooks business ID (get from user_me -> businessMemberships[].business.id)
+- duration: Time in seconds (or ask user for hours/minutes and convert)
+  * 1 hour = 3600 seconds
+  * 1 minute = 60 seconds
+  * Example: 2 hours 30 minutes = 9000 seconds
+
+OPTIONAL BUT RECOMMENDED:
+- note: Description of work performed (improves billing accuracy)
+- projectId: Associate with a project
+- clientId: Associate with a client
+- serviceId: Service type for billing categorization
+- taskId: Associate with a task
+- billable: Whether time is billable (default: true if isLogged=true)
+- startedAt: When work began (ISO 8601 format, defaults to now)
+- isLogged: Whether time is logged (default: true)
+  * Set to false for active timers (with duration=0 and active=true)
+
+SPECIAL CASES:
+- To start a timer: Set duration=0, active=true, isLogged=false
+- For completed work: Set duration to actual seconds, isLogged=true
+
+RETURNS:
+Created time entry with:
+- id: New time entry ID (save this for updates/deletes)
+- duration: Confirmed duration in seconds
+- All other time entry fields
+
+EXAMPLES:
+User says: "Log 2 hours on Project Alpha for code review"
+→ duration: 7200 (2 * 3600)
+→ note: "code review"
+→ projectId: (look up Project Alpha)
+
+User says: "Track 45 minutes of meeting time"
+→ duration: 2700 (45 * 60)
+→ note: "meeting"
+
+User says: "Record 3 hours of development work for client ABC"
+→ duration: 10800 (3 * 3600)
+→ note: "development work"
 → clientId: (look up client ABC)`,
     inputSchema: TimeEntryCreateInputSchema,
     outputSchema: TimeEntrySingleOutputSchema,

package/dist/tools/time-entry/timeentry-delete.js

@@ -11,54 +11,54 @@ import { logger } from '../../utils/logger.js';
  */
 export const timeentryDeleteTool = {
     name: 'timeentry_delete',
-    description: `Delete a time entry from FreshBooks.
-
-WHEN TO USE:
-- User wants to remove a time entry completely
-- User says "delete time entry X", "remove entry Y", "discard this time log"
-- User made a mistake and wants to delete rather than update
-- User wants to discard a running timer without logging the time
-- User asks "delete entry 123", "remove that time entry"
-
-REQUIRED:
-- businessId: FreshBooks business ID (get from user_me -> businessMemberships[].business.id)
-- timeEntryId: ID of the time entry to delete
-
-IMPORTANT NOTES:
-- Deletion is permanent and cannot be undone
-- Use this to discard running timers without logging time
-- If time was already billed, deletion may affect invoices
-- Consider updating instead of deleting if you just need to change values
-
-USE CASES:
-1. Discard a running timer:
-   - Delete the active time entry to discard without logging
-
-2. Remove erroneous entry:
-   - Delete time entries created by mistake
-
-3. Clean up test data:
-   - Remove test or sample time entries
-
-ALTERNATIVE ACTIONS:
-- To change duration/project: Use timeentry_update instead
-- To make non-billable: Use timeentry_update with billable=false
-- To archive: FreshBooks doesn't support archiving (delete removes completely)
-
-RETURNS:
-Success confirmation with:
-- success: true/false
-- message: Confirmation message
-- timeEntryId: ID of the deleted entry
-
-EXAMPLES:
-User says: "Delete time entry 123"
-→ timeEntryId: 123
-
-User says: "Discard timer 456"
-→ timeEntryId: 456
-
-User says: "Remove that time entry I just created"
+    description: `Delete a time entry from FreshBooks.
+
+WHEN TO USE:
+- User wants to remove a time entry completely
+- User says "delete time entry X", "remove entry Y", "discard this time log"
+- User made a mistake and wants to delete rather than update
+- User wants to discard a running timer without logging the time
+- User asks "delete entry 123", "remove that time entry"
+
+REQUIRED:
+- businessId: FreshBooks business ID (get from user_me -> businessMemberships[].business.id)
+- timeEntryId: ID of the time entry to delete
+
+IMPORTANT NOTES:
+- Deletion is permanent and cannot be undone
+- Use this to discard running timers without logging time
+- If time was already billed, deletion may affect invoices
+- Consider updating instead of deleting if you just need to change values
+
+USE CASES:
+1. Discard a running timer:
+   - Delete the active time entry to discard without logging
+
+2. Remove erroneous entry:
+   - Delete time entries created by mistake
+
+3. Clean up test data:
+   - Remove test or sample time entries
+
+ALTERNATIVE ACTIONS:
+- To change duration/project: Use timeentry_update instead
+- To make non-billable: Use timeentry_update with billable=false
+- To archive: FreshBooks doesn't support archiving (delete removes completely)
+
+RETURNS:
+Success confirmation with:
+- success: true/false
+- message: Confirmation message
+- timeEntryId: ID of the deleted entry
+
+EXAMPLES:
+User says: "Delete time entry 123"
+→ timeEntryId: 123
+
+User says: "Discard timer 456"
+→ timeEntryId: 456
+
+User says: "Remove that time entry I just created"
 → (first get the time entry ID, then delete)`,
     inputSchema: TimeEntryDeleteInputSchema,
     outputSchema: TimeEntryDeleteOutputSchema,

package/dist/tools/time-entry/timeentry-list.js

@@ -12,59 +12,59 @@ import { buildQueryBuilders } from '../base-tool.js';
  */
 export const timeentryListTool = {
     name: 'timeentry_list',
-    description: `List time entries from FreshBooks.
-
-WHEN TO USE:
-- User asks to see their time entries, logged hours, or time tracking history
-- User wants to review time for a specific project or client
-- User needs to find entries within a date range
-- User wants to see active/running timers
-- User asks "show my time entries", "what time did I log today", "time on project X"
-
-REQUIRED:
-- businessId: FreshBooks business ID (get from user_me -> businessMemberships[].business.id)
-
-OPTIONAL FILTERS:
-- projectId: Filter by specific project
-- clientId: Filter by specific client
-- taskId: Filter by specific task
-- serviceId: Filter by specific service
-- active: Filter by active status (true = running timers only)
-- billable: Filter by billable status
-- billed: Filter by whether already billed
-- startedAfter: Show entries after this date (ISO 8601)
-- startedBefore: Show entries before this date (ISO 8601)
-
-SORTING:
-- sortBy: Field to sort by (started_at, created_at, duration)
-- sortOrder: Sort direction (asc or desc, default: desc for most recent first)
-
-INCLUDES:
-- include: Related data to fetch (client, project, task, service)
-  - client: Client details associated with the time entry
-  - project: Project details for the time entry
-  - task: Task information if assigned
-  - service: Service type for billing categorization
-
-PAGINATION:
-- page: Page number (default: 1)
-- perPage: Results per page (default: 30, max: 100)
-
-RETURNS:
-Array of time entries with:
-- duration: Time in seconds
-- note: Description of work
-- startedAt: When the entry began
-- projectId, clientId, taskId, serviceId: Associated entities
-- billable, billed: Billing status
-- active: Whether timer is currently running
-Plus pagination metadata (page, pages, total)
-
-EXAMPLES:
-- "Show my time entries for today"
-- "List time logged on project 123"
-- "Show billable time entries from last week"
-- "Find active timers sorted by duration"
+    description: `List time entries from FreshBooks.
+
+WHEN TO USE:
+- User asks to see their time entries, logged hours, or time tracking history
+- User wants to review time for a specific project or client
+- User needs to find entries within a date range
+- User wants to see active/running timers
+- User asks "show my time entries", "what time did I log today", "time on project X"
+
+REQUIRED:
+- businessId: FreshBooks business ID (get from user_me -> businessMemberships[].business.id)
+
+OPTIONAL FILTERS:
+- projectId: Filter by specific project
+- clientId: Filter by specific client
+- taskId: Filter by specific task
+- serviceId: Filter by specific service
+- active: Filter by active status (true = running timers only)
+- billable: Filter by billable status
+- billed: Filter by whether already billed
+- startedAfter: Show entries after this date (ISO 8601)
+- startedBefore: Show entries before this date (ISO 8601)
+
+SORTING:
+- sortBy: Field to sort by (started_at, created_at, duration)
+- sortOrder: Sort direction (asc or desc, default: desc for most recent first)
+
+INCLUDES:
+- include: Related data to fetch (client, project, task, service)
+  - client: Client details associated with the time entry
+  - project: Project details for the time entry
+  - task: Task information if assigned
+  - service: Service type for billing categorization
+
+PAGINATION:
+- page: Page number (default: 1)
+- perPage: Results per page (default: 30, max: 100)
+
+RETURNS:
+Array of time entries with:
+- duration: Time in seconds
+- note: Description of work
+- startedAt: When the entry began
+- projectId, clientId, taskId, serviceId: Associated entities
+- billable, billed: Billing status
+- active: Whether timer is currently running
+Plus pagination metadata (page, pages, total)
+
+EXAMPLES:
+- "Show my time entries for today"
+- "List time logged on project 123"
+- "Show billable time entries from last week"
+- "Find active timers sorted by duration"
 - "Get time entries with project details included"`,
     inputSchema: TimeEntryListInputSchema,
     outputSchema: TimeEntryListOutputSchema,

package/dist/tools/time-entry/timeentry-single.js

@@ -11,34 +11,34 @@ import { logger } from '../../utils/logger.js';
  */
 export const timeentrySingleTool = {
     name: 'timeentry_single',
-    description: `Get a single time entry by ID from FreshBooks.
-
-WHEN TO USE:
-- User wants to see details of a specific time entry
-- User references a time entry ID and wants full information
-- User asks "show time entry 123", "get details for entry X"
-- Need to retrieve a time entry before updating or deleting it
-
-REQUIRED:
-- businessId: FreshBooks business ID (get from user_me -> businessMemberships[].business.id)
-- timeEntryId: The ID of the time entry to retrieve
-
-RETURNS:
-Complete time entry object with:
-- id: Time entry ID
-- duration: Time in seconds
-- note: Description of work
-- startedAt: When the entry began
-- createdAt: When the entry was created
-- projectId, clientId, taskId, serviceId: Associated entities
-- billable, billed: Billing status
-- active: Whether timer is currently running
-- timer: Active timer object if running
-- All other time entry fields
-
-EXAMPLES:
-- "Show me time entry 456"
-- "Get details for time entry ID 789"
+    description: `Get a single time entry by ID from FreshBooks.
+
+WHEN TO USE:
+- User wants to see details of a specific time entry
+- User references a time entry ID and wants full information
+- User asks "show time entry 123", "get details for entry X"
+- Need to retrieve a time entry before updating or deleting it
+
+REQUIRED:
+- businessId: FreshBooks business ID (get from user_me -> businessMemberships[].business.id)
+- timeEntryId: The ID of the time entry to retrieve
+
+RETURNS:
+Complete time entry object with:
+- id: Time entry ID
+- duration: Time in seconds
+- note: Description of work
+- startedAt: When the entry began
+- createdAt: When the entry was created
+- projectId, clientId, taskId, serviceId: Associated entities
+- billable, billed: Billing status
+- active: Whether timer is currently running
+- timer: Active timer object if running
+- All other time entry fields
+
+EXAMPLES:
+- "Show me time entry 456"
+- "Get details for time entry ID 789"
 - "What's in time entry 123?"`,
     inputSchema: TimeEntrySingleInputSchema,
     outputSchema: TimeEntrySingleOutputSchema,

package/dist/tools/time-entry/timeentry-update.js

@@ -11,67 +11,67 @@ import { logger } from '../../utils/logger.js';
  */
 export const timeentryUpdateTool = {
     name: 'timeentry_update',
-    description: `Update an existing time entry in FreshBooks.
-
-WHEN TO USE:
-- User wants to modify a time entry
-- User says "update time entry X", "change the duration", "edit my time log"
-- User needs to correct duration, note, or project association
-- User wants to stop a running timer (set active=false)
-- User asks "update entry 123 to 3 hours", "change project on entry 456"
-
-REQUIRED:
-- businessId: FreshBooks business ID (get from user_me -> businessMemberships[].business.id)
-- timeEntryId: ID of the time entry to update
-
-OPTIONAL (provide only fields to change):
-- duration: New duration in seconds
-- note: New or updated description
-- projectId: Change project association (null to remove)
-- clientId: Change client association (null to remove)
-- serviceId: Change service association (null to remove)
-- taskId: Change task association (null to remove)
-- billable: Change billable status
-- active: Stop/start timer (false to stop, true to restart)
-- isLogged: Change logged status
-- startedAt: Change start time
-- internal: Change internal work flag
-- retainerId: Change retainer association
-
-COMMON USE CASES:
-1. Stop a running timer:
-   - Set active=false (duration auto-calculated from startedAt)
-
-2. Change duration:
-   - Set new duration in seconds
-
-3. Update note:
-   - Set new note text
-
-4. Change project:
-   - Set new projectId
-
-5. Make non-billable:
-   - Set billable=false
-
-RETURNS:
-Updated time entry with all fields (including unchanged ones)
-
-EXAMPLES:
-User says: "Update time entry 123 to 3 hours"
-→ timeEntryId: 123
-→ duration: 10800
-
-User says: "Stop timer 456"
-→ timeEntryId: 456
-→ active: false
-
-User says: "Change the note on entry 789 to 'code review'"
-→ timeEntryId: 789
-→ note: "code review"
-
-User says: "Make entry 321 non-billable"
-→ timeEntryId: 321
+    description: `Update an existing time entry in FreshBooks.
+
+WHEN TO USE:
+- User wants to modify a time entry
+- User says "update time entry X", "change the duration", "edit my time log"
+- User needs to correct duration, note, or project association
+- User wants to stop a running timer (set active=false)
+- User asks "update entry 123 to 3 hours", "change project on entry 456"
+
+REQUIRED:
+- businessId: FreshBooks business ID (get from user_me -> businessMemberships[].business.id)
+- timeEntryId: ID of the time entry to update
+
+OPTIONAL (provide only fields to change):
+- duration: New duration in seconds
+- note: New or updated description
+- projectId: Change project association (null to remove)
+- clientId: Change client association (null to remove)
+- serviceId: Change service association (null to remove)
+- taskId: Change task association (null to remove)
+- billable: Change billable status
+- active: Stop/start timer (false to stop, true to restart)
+- isLogged: Change logged status
+- startedAt: Change start time
+- internal: Change internal work flag
+- retainerId: Change retainer association
+
+COMMON USE CASES:
+1. Stop a running timer:
+   - Set active=false (duration auto-calculated from startedAt)
+
+2. Change duration:
+   - Set new duration in seconds
+
+3. Update note:
+   - Set new note text
+
+4. Change project:
+   - Set new projectId
+
+5. Make non-billable:
+   - Set billable=false
+
+RETURNS:
+Updated time entry with all fields (including unchanged ones)
+
+EXAMPLES:
+User says: "Update time entry 123 to 3 hours"
+→ timeEntryId: 123
+→ duration: 10800
+
+User says: "Stop timer 456"
+→ timeEntryId: 456
+→ active: false
+
+User says: "Change the note on entry 789 to 'code review'"
+→ timeEntryId: 789
+→ note: "code review"
+
+User says: "Make entry 321 non-billable"
+→ timeEntryId: 321
 → billable: false`,
     inputSchema: TimeEntryUpdateInputSchema,
     outputSchema: TimeEntrySingleOutputSchema,

package/dist/tools/timer/timer-current.js

@@ -13,60 +13,60 @@ import { ErrorHandler } from "../../errors/error-handler.js";
  */
 export const timerCurrentTool = {
     name: "timer_current",
-    description: `Get the currently running timer(s) in FreshBooks.
-
-WHEN TO USE:
-- User asks "what timer is running?", "show my current timer", "am I tracking time?"
-- Need to find timer ID before stopping it
-- Want to check if any timer is active before starting a new one
-- Need to see timer details (duration so far, project, notes)
-
-HOW IT WORKS:
-Searches for time entries with:
-- active=true (timer is currently running)
-- Returns all matching entries (typically 0 or 1)
-
-TYPICAL RESULTS:
-- 0 timers: No timer is currently running
-- 1 timer: The active timer with details
-- Multiple timers: Rare, but possible in some FreshBooks configurations
-
-REQUIRED:
-- businessId: FreshBooks business ID (get from user_me -> businessMemberships[].business.id)
-
-NO ACTIVE TIMER:
-If no timer is running, returns:
-- activeTimers: [] (empty array)
-- count: 0
-
-ACTIVE TIMER DETAILS:
-Each active timer includes:
-- id: Time entry ID (use this to stop or discard)
-- startedAt: When timer started (ISO 8601 timestamp)
-- duration: Current duration in seconds (calculated from start time)
-- projectId: Associated project (if any)
-- clientId: Associated client (if any)
-- note: Work description (if any)
-- billable: Whether time is billable
-- timer: Nested timer object with isRunning=true
-
-CALCULATING ELAPSED TIME:
-The duration field shows elapsed seconds, but it may not be real-time.
-To calculate current elapsed time:
-- Parse startedAt timestamp
-- Calculate difference from now
-- Result is current elapsed time
-
-EXAMPLE USAGE:
-- "Show my current timer"
-- "What am I tracking time for?"
-- "How long has my timer been running?"
-- "Is there a timer running?"
-
-NEXT STEPS:
-If timer is found, you can:
-- Stop it: Use timer_stop with the returned id
-- Discard it: Use timer_discard with the returned id
+    description: `Get the currently running timer(s) in FreshBooks.
+
+WHEN TO USE:
+- User asks "what timer is running?", "show my current timer", "am I tracking time?"
+- Need to find timer ID before stopping it
+- Want to check if any timer is active before starting a new one
+- Need to see timer details (duration so far, project, notes)
+
+HOW IT WORKS:
+Searches for time entries with:
+- active=true (timer is currently running)
+- Returns all matching entries (typically 0 or 1)
+
+TYPICAL RESULTS:
+- 0 timers: No timer is currently running
+- 1 timer: The active timer with details
+- Multiple timers: Rare, but possible in some FreshBooks configurations
+
+REQUIRED:
+- businessId: FreshBooks business ID (get from user_me -> businessMemberships[].business.id)
+
+NO ACTIVE TIMER:
+If no timer is running, returns:
+- activeTimers: [] (empty array)
+- count: 0
+
+ACTIVE TIMER DETAILS:
+Each active timer includes:
+- id: Time entry ID (use this to stop or discard)
+- startedAt: When timer started (ISO 8601 timestamp)
+- duration: Current duration in seconds (calculated from start time)
+- projectId: Associated project (if any)
+- clientId: Associated client (if any)
+- note: Work description (if any)
+- billable: Whether time is billable
+- timer: Nested timer object with isRunning=true
+
+CALCULATING ELAPSED TIME:
+The duration field shows elapsed seconds, but it may not be real-time.
+To calculate current elapsed time:
+- Parse startedAt timestamp
+- Calculate difference from now
+- Result is current elapsed time
+
+EXAMPLE USAGE:
+- "Show my current timer"
+- "What am I tracking time for?"
+- "How long has my timer been running?"
+- "Is there a timer running?"
+
+NEXT STEPS:
+If timer is found, you can:
+- Stop it: Use timer_stop with the returned id
+- Discard it: Use timer_discard with the returned id
 - Continue running: Do nothing, timer keeps tracking`,
     inputSchema: TimerCurrentInputSchema,
     outputSchema: TimerCurrentOutputSchema,