@goodsamsoftware/freshbooks-mcp 1.0.6 → 1.0.8

package/dist/tools/project/project-list.js

@@ -11,44 +11,44 @@ import { buildQueryBuilders } from "../base-tool.js";
  */
 export const projectListTool = {
     name: "project_list",
-    description: `List projects from FreshBooks with optional filtering and pagination.
-
-WHEN TO USE:
-- User asks to "see projects", "list projects", "show all projects"
-- User wants to find a project by name or client
-- User needs project information for time tracking context
-
-FILTERING OPTIONS:
-- clientId: Filter by specific client
-- active: Show only active/inactive projects
-- complete: Show only complete/incomplete projects
-- internal: Show only internal/billable projects
-- title: Search by project name (partial match)
-
-SORTING:
-- sortBy: Field to sort by (title, created_at, due_date)
-- sortOrder: Sort direction (asc or desc, default: desc)
-
-INCLUDES:
-- include: Related data to fetch (client, services, group)
-  - client: Client details associated with the project
-  - services: Service/billing rate configurations
-  - group: Project group for organization
-
-PAGINATION:
-- Use page/perPage for large result sets
-- Default: 30 results per page
-- Maximum: 100 results per page
-
-EXAMPLE PROMPTS:
-- "Show me all active projects"
-- "List projects for client ABC123"
-- "Find projects with 'Website' in the title"
-- "Show incomplete projects sorted by due date"
-- "Get projects with client details included"
-
-RETURNS:
-Array of projects with titles, clients, billing info, and time logged.
+    description: `List projects from FreshBooks with optional filtering and pagination.
+
+WHEN TO USE:
+- User asks to "see projects", "list projects", "show all projects"
+- User wants to find a project by name or client
+- User needs project information for time tracking context
+
+FILTERING OPTIONS:
+- clientId: Filter by specific client
+- active: Show only active/inactive projects
+- complete: Show only complete/incomplete projects
+- internal: Show only internal/billable projects
+- title: Search by project name (partial match)
+
+SORTING:
+- sortBy: Field to sort by (title, created_at, due_date)
+- sortOrder: Sort direction (asc or desc, default: desc)
+
+INCLUDES:
+- include: Related data to fetch (client, services, group)
+  - client: Client details associated with the project
+  - services: Service/billing rate configurations
+  - group: Project group for organization
+
+PAGINATION:
+- Use page/perPage for large result sets
+- Default: 30 results per page
+- Maximum: 100 results per page
+
+EXAMPLE PROMPTS:
+- "Show me all active projects"
+- "List projects for client ABC123"
+- "Find projects with 'Website' in the title"
+- "Show incomplete projects sorted by due date"
+- "Get projects with client details included"
+
+RETURNS:
+Array of projects with titles, clients, billing info, and time logged.
 Includes pagination metadata for navigating large result sets.`,
     inputSchema: ProjectListInputSchema,
     outputSchema: ProjectListOutputSchema,

package/dist/tools/project/project-single.js

@@ -10,29 +10,29 @@ import { ErrorHandler } from "../../errors/error-handler.js";
  */
 export const projectSingleTool = {
     name: "project_single",
-    description: `Get detailed information about a specific project by ID.
-
-WHEN TO USE:
-- User asks for details about a specific project
-- User provides a project ID or name from a previous list
-- Need full project information including rates and billing settings
-
-REQUIRED INFO:
-- Project ID (numeric)
-- Account ID (get from context or user)
-
-OPTIONAL INCLUDES:
-- client: Include full client details
-- services: Include associated service definitions
-- group: Include project group information
-
-EXAMPLE PROMPTS:
-- "Show me details for project 12345"
-- "Get information about the Website Redesign project"
-- "What's the billing method for project 98765?"
-
-RETURNS:
-Complete project details including title, description, client, billing method,
+    description: `Get detailed information about a specific project by ID.
+
+WHEN TO USE:
+- User asks for details about a specific project
+- User provides a project ID or name from a previous list
+- Need full project information including rates and billing settings
+
+REQUIRED INFO:
+- Project ID (numeric)
+- Account ID (get from context or user)
+
+OPTIONAL INCLUDES:
+- client: Include full client details
+- services: Include associated service definitions
+- group: Include project group information
+
+EXAMPLE PROMPTS:
+- "Show me details for project 12345"
+- "Get information about the Website Redesign project"
+- "What's the billing method for project 98765?"
+
+RETURNS:
+Complete project details including title, description, client, billing method,
 rates, time logged, completion status, and financial totals.`,
     inputSchema: ProjectSingleInputSchema,
     outputSchema: ProjectSingleOutputSchema,

package/dist/tools/project/project-update.js

@@ -10,43 +10,43 @@ import { ErrorHandler } from "../../errors/error-handler.js";
  */
 export const projectUpdateTool = {
     name: "project_update",
-    description: `Update an existing project in FreshBooks.
-
-WHEN TO USE:
-- User wants to modify project details
-- User says "update project", "change project", "mark project complete"
-- Adjusting billing rates, due dates, or status
-
-REQUIRED INFO:
-- projectId: Which project to update (numeric)
-- accountId: FreshBooks account (get from context)
-
-UPDATABLE FIELDS:
-- title: Change project name
-- description: Update project description
-- dueDate: Change completion deadline (ISO 8601)
-- clientId: Reassign to different client
-- billingMethod: Change how project is billed
-- rate: Update hourly rate
-- fixedPrice: Change fixed price amount
-- budget: Adjust project budget
-- active: Activate or deactivate project
-- complete: Mark project as complete/incomplete
-- internal: Change billable status
-
-STATUS CHANGES:
-- Set active=false to pause project (stops appearing in active lists)
-- Set complete=true to mark project done
-- Both can be combined for archival
-
-EXAMPLE PROMPTS:
-- "Mark project 12345 as complete"
-- "Update project Website Redesign to increase rate to $150/hr"
-- "Change project 98765 due date to next Friday"
-- "Deactivate project Mobile App"
-
-RETURNS:
-Updated project with all current settings. Changes take effect immediately
+    description: `Update an existing project in FreshBooks.
+
+WHEN TO USE:
+- User wants to modify project details
+- User says "update project", "change project", "mark project complete"
+- Adjusting billing rates, due dates, or status
+
+REQUIRED INFO:
+- projectId: Which project to update (numeric)
+- accountId: FreshBooks account (get from context)
+
+UPDATABLE FIELDS:
+- title: Change project name
+- description: Update project description
+- dueDate: Change completion deadline (ISO 8601)
+- clientId: Reassign to different client
+- billingMethod: Change how project is billed
+- rate: Update hourly rate
+- fixedPrice: Change fixed price amount
+- budget: Adjust project budget
+- active: Activate or deactivate project
+- complete: Mark project as complete/incomplete
+- internal: Change billable status
+
+STATUS CHANGES:
+- Set active=false to pause project (stops appearing in active lists)
+- Set complete=true to mark project done
+- Both can be combined for archival
+
+EXAMPLE PROMPTS:
+- "Mark project 12345 as complete"
+- "Update project Website Redesign to increase rate to $150/hr"
+- "Change project 98765 due date to next Friday"
+- "Deactivate project Mobile App"
+
+RETURNS:
+Updated project with all current settings. Changes take effect immediately
 for new time entries.`,
     inputSchema: ProjectUpdateInputSchema,
     outputSchema: ProjectSingleOutputSchema,

package/dist/tools/task/task-create.js

@@ -10,42 +10,42 @@ import { ErrorHandler } from '../../errors/error-handler.js';
  */
 export const taskCreateTool = {
     name: 'task_create',
-    description: `Create a new task in FreshBooks.
-
-WHEN TO USE:
-- User needs a new task category
-- Setting up task breakdown for a project
-- Creating specialized tracking categories
-- Organizing work into billable tasks
-
-REQUIRED INFO:
-- accountId: FreshBooks account ID
-- name: Task name (descriptive label)
-
-OPTIONAL PARAMETERS:
-- description: Detailed task description
-- billable: Whether task is billable (default: true)
-- rate: Task-specific billing rate
-  - amount: Decimal string (e.g., "50.00")
-  - code: Currency code (default: USD)
-
-RETURNS:
-Created task with:
-- Task ID (for use in time entries)
-- Name, description
-- Billable status and rate
-- Visibility state
-
-EXAMPLE PROMPTS:
-- "Create a task called Code Review"
-- "Add a new billable task for Testing"
-- "Set up a task for Documentation at $45/hour"
-- "Create a non-billable task for Internal Meetings"
-
-BEST PRACTICES:
-- Use clear, specific task names
-- Set appropriate rates for different task types
-- Create non-billable tasks for internal work
+    description: `Create a new task in FreshBooks.
+
+WHEN TO USE:
+- User needs a new task category
+- Setting up task breakdown for a project
+- Creating specialized tracking categories
+- Organizing work into billable tasks
+
+REQUIRED INFO:
+- accountId: FreshBooks account ID
+- name: Task name (descriptive label)
+
+OPTIONAL PARAMETERS:
+- description: Detailed task description
+- billable: Whether task is billable (default: true)
+- rate: Task-specific billing rate
+  - amount: Decimal string (e.g., "50.00")
+  - code: Currency code (default: USD)
+
+RETURNS:
+Created task with:
+- Task ID (for use in time entries)
+- Name, description
+- Billable status and rate
+- Visibility state
+
+EXAMPLE PROMPTS:
+- "Create a task called Code Review"
+- "Add a new billable task for Testing"
+- "Set up a task for Documentation at $45/hour"
+- "Create a non-billable task for Internal Meetings"
+
+BEST PRACTICES:
+- Use clear, specific task names
+- Set appropriate rates for different task types
+- Create non-billable tasks for internal work
 - Add descriptions to clarify task purpose`,
     inputSchema: TaskCreateInputSchema,
     outputSchema: TaskSchema,

package/dist/tools/task/task-delete.js

@@ -11,41 +11,41 @@ import { ErrorHandler } from '../../errors/error-handler.js';
  */
 export const taskDeleteTool = {
     name: 'task_delete',
-    description: `Delete a task from FreshBooks.
-
-WHEN TO USE:
-- Need to permanently remove a task
-- Cleaning up test/duplicate tasks
-- Removing incorrectly created tasks
-
-REQUIRED INFO:
-- accountId: FreshBooks account ID
-- taskId: Task ID (numeric identifier)
-
-IMPORTANT WARNINGS:
-- This is PERMANENT and IRREVERSIBLE
-- Cannot recover deleted tasks
-- Consider using task_update with visState=1 to archive instead
-- Deleted tasks cannot be used in new time entries
-- Existing time entries with this task will retain the reference
-
-RETURNS:
-Success confirmation:
-- success: true if deleted
-- message: Confirmation message
-
-EXAMPLE PROMPTS:
-- "Delete task 12345"
-- "Remove task ID 789"
-- "Permanently delete the Testing task"
-
-BEST PRACTICE:
-⚠️ ARCHIVE INSTEAD: Use task_update with visState=1 to soft-delete tasks.
-This preserves data integrity while hiding the task from active lists.
-
-DELETE ONLY IF:
-- Task was created by mistake
-- Task has no time entries associated
+    description: `Delete a task from FreshBooks.
+
+WHEN TO USE:
+- Need to permanently remove a task
+- Cleaning up test/duplicate tasks
+- Removing incorrectly created tasks
+
+REQUIRED INFO:
+- accountId: FreshBooks account ID
+- taskId: Task ID (numeric identifier)
+
+IMPORTANT WARNINGS:
+- This is PERMANENT and IRREVERSIBLE
+- Cannot recover deleted tasks
+- Consider using task_update with visState=1 to archive instead
+- Deleted tasks cannot be used in new time entries
+- Existing time entries with this task will retain the reference
+
+RETURNS:
+Success confirmation:
+- success: true if deleted
+- message: Confirmation message
+
+EXAMPLE PROMPTS:
+- "Delete task 12345"
+- "Remove task ID 789"
+- "Permanently delete the Testing task"
+
+BEST PRACTICE:
+⚠️ ARCHIVE INSTEAD: Use task_update with visState=1 to soft-delete tasks.
+This preserves data integrity while hiding the task from active lists.
+
+DELETE ONLY IF:
+- Task was created by mistake
+- Task has no time entries associated
 - You're absolutely certain it should be removed`,
     inputSchema: TaskDeleteInputSchema,
     outputSchema: DeleteSuccessSchema,

package/dist/tools/task/task-list.js

@@ -14,34 +14,34 @@ const InputSchema = AccountIdSchema.extend({
  */
 export const taskListTool = {
     name: 'task_list',
-    description: `List tasks from FreshBooks.
-
-WHEN TO USE:
-- User wants to see project tasks
-- Need to find a task ID for time entry
-- Browse available task categories
-- Review task organization
-
-REQUIRED INFO:
-- accountId: FreshBooks account ID
-
-OPTIONAL PARAMETERS:
-- page: Page number for pagination (default: 1)
-- perPage: Results per page (default: 30, max: 100)
-
-RETURNS:
-Array of tasks with:
-- Task ID, name, description
-- Billable status and rate
-- Visibility state (active/archived)
-- Pagination metadata
-
-EXAMPLE PROMPTS:
-- "Show me all tasks"
-- "List project tasks"
-- "What tasks can I assign time to?"
-- "Get all billable tasks"
-
+    description: `List tasks from FreshBooks.
+
+WHEN TO USE:
+- User wants to see project tasks
+- Need to find a task ID for time entry
+- Browse available task categories
+- Review task organization
+
+REQUIRED INFO:
+- accountId: FreshBooks account ID
+
+OPTIONAL PARAMETERS:
+- page: Page number for pagination (default: 1)
+- perPage: Results per page (default: 30, max: 100)
+
+RETURNS:
+Array of tasks with:
+- Task ID, name, description
+- Billable status and rate
+- Visibility state (active/archived)
+- Pagination metadata
+
+EXAMPLE PROMPTS:
+- "Show me all tasks"
+- "List project tasks"
+- "What tasks can I assign time to?"
+- "Get all billable tasks"
+
 NOTE: Tasks can have alternate field names (name/tname, description/tdesc) in the API.`,
     inputSchema: InputSchema,
     outputSchema: TaskListOutputSchema,

package/dist/tools/task/task-single.js

@@ -10,31 +10,31 @@ import { ErrorHandler } from '../../errors/error-handler.js';
  */
 export const taskSingleTool = {
     name: 'task_single',
-    description: `Get a single task by ID from FreshBooks.
-
-WHEN TO USE:
-- Need detailed information about a specific task
-- Verify task settings before using
-- Check task rate and billable status
-- Confirm task exists
-
-REQUIRED INFO:
-- accountId: FreshBooks account ID
-- taskId: Task ID (numeric identifier)
-
-RETURNS:
-Complete task details including:
-- Task ID, name, description
-- Billable status and rate
-- Visibility state
-- Last update timestamp
-
-EXAMPLE PROMPTS:
-- "Get details for task 12345"
-- "Show me task information for ID 789"
-- "What is task 456 used for?"
-- "Check if task 123 is billable"
-
+    description: `Get a single task by ID from FreshBooks.
+
+WHEN TO USE:
+- Need detailed information about a specific task
+- Verify task settings before using
+- Check task rate and billable status
+- Confirm task exists
+
+REQUIRED INFO:
+- accountId: FreshBooks account ID
+- taskId: Task ID (numeric identifier)
+
+RETURNS:
+Complete task details including:
+- Task ID, name, description
+- Billable status and rate
+- Visibility state
+- Last update timestamp
+
+EXAMPLE PROMPTS:
+- "Get details for task 12345"
+- "Show me task information for ID 789"
+- "What is task 456 used for?"
+- "Check if task 123 is billable"
+
 NOTE: Task names may appear in either 'name' or 'tname' field due to API variations.`,
     inputSchema: TaskSingleInputSchema,
     outputSchema: TaskSchema,

package/dist/tools/task/task-update.js

@@ -10,45 +10,45 @@ import { ErrorHandler } from '../../errors/error-handler.js';
  */
 export const taskUpdateTool = {
     name: 'task_update',
-    description: `Update an existing task in FreshBooks.
-
-WHEN TO USE:
-- Need to change task name or description
-- Update billing rate for a task
-- Change billable status
-- Archive a task (set visState)
-
-REQUIRED INFO:
-- accountId: FreshBooks account ID
-- taskId: Task ID (numeric identifier)
-
-OPTIONAL PARAMETERS (at least one required):
-- name: Updated task name
-- description: Updated task description
-- billable: Updated billable status
-- rate: Updated billing rate
-  - amount: Decimal string (e.g., "60.00")
-  - code: Currency code
-- visState: Visibility state (0=active, 1=deleted, 2=archived)
-
-RETURNS:
-Updated task with:
-- Task ID (unchanged)
-- New name, description, rate
-- Updated billable status
-- Updated visibility state
-
-EXAMPLE PROMPTS:
-- "Update task 123 to be non-billable"
-- "Change task 456 name to Development Work"
-- "Set task 789 rate to $85/hour"
-- "Archive task 234"
-- "Update task 567 description to include meetings"
-
-BEST PRACTICES:
-- Use visState to archive rather than delete
-- Update rates when billing changes
-- Keep task names and descriptions current
+    description: `Update an existing task in FreshBooks.
+
+WHEN TO USE:
+- Need to change task name or description
+- Update billing rate for a task
+- Change billable status
+- Archive a task (set visState)
+
+REQUIRED INFO:
+- accountId: FreshBooks account ID
+- taskId: Task ID (numeric identifier)
+
+OPTIONAL PARAMETERS (at least one required):
+- name: Updated task name
+- description: Updated task description
+- billable: Updated billable status
+- rate: Updated billing rate
+  - amount: Decimal string (e.g., "60.00")
+  - code: Currency code
+- visState: Visibility state (0=active, 1=deleted, 2=archived)
+
+RETURNS:
+Updated task with:
+- Task ID (unchanged)
+- New name, description, rate
+- Updated billable status
+- Updated visibility state
+
+EXAMPLE PROMPTS:
+- "Update task 123 to be non-billable"
+- "Change task 456 name to Development Work"
+- "Set task 789 rate to $85/hour"
+- "Archive task 234"
+- "Update task 567 description to include meetings"
+
+BEST PRACTICES:
+- Use visState to archive rather than delete
+- Update rates when billing changes
+- Keep task names and descriptions current
 - Mark internal tasks as non-billable`,
     inputSchema: TaskUpdateInputSchema,
     outputSchema: TaskSchema,