about

Instructions

Implementation Reference

• src/index.ts:151-161 (handler)

  MCP server request handler specifically for the 'about' tool. Dispatches to harvestClient.getAboutInfo() and formats the response as MCP text content.

  // About Tool
  case 'about':
    const aboutInfo = harvestClient.getAboutInfo(typedArgs?.tool as string);
    return {
      content: [
        {
          type: 'text',
          text: aboutInfo,
        },
      ],
    };

• src/tools.ts:85-93 (schema)

  Tool definition object including name, description, and inputSchema for the 'about' tool. This is used for MCP tool listing and validation.

    name: 'about',
    description: 'Get detailed information about the Harvest MCP server and its tools. Call about without parameters for general info, or with {"tool": "tool_name"} for specific tool documentation.',
    inputSchema: {
      type: 'object',
      properties: {
        tool: { type: 'string', description: 'Optional: specific tool name to get detailed information about' }
      }
    }
  },

• src/harvest-client.ts:179-931 (helper)

  Core helper method getAboutInfo() that returns detailed markdown documentation for the entire server or specific tools. Called by the 'about' handler.

    getAboutInfo(toolName?: string): string {
      if (!toolName) {
        return `# Harvest MCP Server
  
  A comprehensive Model Context Protocol server for Harvest API v2 integration, providing complete time tracking and project management functionality.
  
  ## Overview
  This MCP server connects AI assistants (like Claude) to your Harvest account, enabling natural language time tracking, project management, and reporting. It provides 15 specialized tools covering all aspects of time tracking workflow.
  
  ## Core Capabilities
  - **Time Entry Management**: Create, update, delete, and list time entries with filtering
  - **Timer Operations**: Start, stop, and restart timers for active time tracking
  - **Project & Task Management**: Access project details, tasks, and assignments
  - **User & Client Management**: Manage users and client information
  - **Reporting**: Generate detailed time reports with date ranges
  - **Assignment Management**: View project and task assignments
  
  ## Tool Categories
  
  ### Time Tracking Tools (6 tools)
  - harvest_list_time_entries, harvest_create_time_entry, harvest_update_time_entry
  - harvest_delete_time_entry, harvest_restart_timer, harvest_stop_timer
  
  ### Project Management Tools (3 tools)  
  - harvest_list_projects, harvest_get_project, harvest_list_tasks
  
  ### User Management Tools (3 tools)
  - harvest_get_current_user, harvest_list_users, harvest_list_clients
  
  ### Reporting & Assignment Tools (3 tools)
  - harvest_time_report, harvest_list_project_assignments, harvest_list_task_assignments
  
  ## Example Usage Patterns
  
  **Start a work session:**
  1. List projects: harvest_list_projects
  2. Create time entry: harvest_create_time_entry 
  3. Start timer: harvest_restart_timer
  
  **End work session:**
  1. Stop timer: harvest_stop_timer
  2. Update notes: harvest_update_time_entry
  
  **Generate reports:**
  1. Get time report: harvest_time_report with date range
  2. Filter by user or project as needed
  
  **For detailed information about any specific tool, use:**
  about {"tool": "tool_name"}
  
  ## Authentication
  Uses Harvest API v2 with personal access tokens. Requires HARVEST_ACCOUNT_ID and HARVEST_ACCESS_TOKEN environment variables.
  
  ## Response Format
  All tools return JSON data from the Harvest API, formatted for easy consumption by AI assistants.`;
      }
  
      const toolDetails: Record<string, string> = {
        'harvest_list_time_entries': `# harvest_list_time_entries
  
  Lists time entries with powerful filtering and pagination options.
  
  ## Purpose
  Retrieve time entries from your Harvest account with optional filters for users, projects, date ranges, and pagination.
  
  ## Parameters
  - \`user_id\` (string, optional): Filter entries by specific user ID
  - \`project_id\` (string, optional): Filter entries by specific project ID  
  - \`from\` (string, optional): Start date in YYYY-MM-DD format
  - \`to\` (string, optional): End date in YYYY-MM-DD format
  - \`page\` (number, optional): Page number for pagination (default: 1)
  - \`per_page\` (number, optional): Results per page, max 100 (default: 100)
  
  ## Example Usage
  
  **List all time entries:**
  \`\`\`json
  {"tool": "harvest_list_time_entries"}
  \`\`\`
  
  **List entries for last week:**
  \`\`\`json
  {
    "tool": "harvest_list_time_entries",
    "from": "2024-01-15",
    "to": "2024-01-21"
  }
  \`\`\`
  
  **List entries for specific project with pagination:**
  \`\`\`json
  {
    "tool": "harvest_list_time_entries", 
    "project_id": "12345",
    "page": 1,
    "per_page": 25
  }
  \`\`\`
  
  ## Response Format
  Returns an object with:
  - \`time_entries\`: Array of time entry objects
  - \`per_page\`, \`total_pages\`, \`total_entries\`: Pagination info
  - \`page\`, \`links\`: Current page and navigation links
  
  Each time entry includes: id, hours, notes, spent_date, project info, task info, user info, timer status (is_running, timer_started_at).`,
  
        'harvest_create_time_entry': `# harvest_create_time_entry
  
  Creates a new time entry in your Harvest account.
  
  ## Purpose  
  Create a time entry for tracking work on a specific project and task. Can be created with specific hours or without hours to start a timer.
  
  ## Parameters
  - \`project_id\` (string, required): The project ID to log time against
  - \`task_id\` (string, required): The task ID within the project
  - \`spent_date\` (string, required): Date for the entry in YYYY-MM-DD format
  - \`hours\` (number, optional): Hours worked (omit to start a timer)
  - \`notes\` (string, optional): Notes or description for the time entry
  
  ## Example Usage
  
  **Create entry with specific hours:**
  \`\`\`json
  {
    "tool": "harvest_create_time_entry",
    "project_id": "12345", 
    "task_id": "67890",
    "spent_date": "2024-01-20",
    "hours": 2.5,
    "notes": "Worked on API integration"
  }
  \`\`\`
  
  **Create entry and start timer (no hours specified):**
  \`\`\`json
  {
    "tool": "harvest_create_time_entry",
    "project_id": "12345",
    "task_id": "67890", 
    "spent_date": "2024-01-20",
    "notes": "Starting work on feature development"
  }
  \`\`\`
  
  ## Response Format
  Returns the created time entry object with:
  - \`id\`: Unique time entry ID
  - \`hours\`: Hours logged (or 0 if timer started)
  - \`is_running\`: Timer status
  - \`timer_started_at\`: Timer start time (if applicable)
  - \`project\`, \`task\`, \`user\`: Associated objects
  - All other time entry properties
  
  ## Workflow Tips
  - Use harvest_list_projects to find project_id
  - Use harvest_list_task_assignments to find valid task_id for the project
  - Omit hours parameter to create a running timer entry`,
  
        'harvest_update_time_entry': `# harvest_update_time_entry
  
  Updates an existing time entry with new information.
  
  ## Purpose
  Modify any aspect of an existing time entry including hours, notes, project, task, or date.
  
  ## Parameters
  - \`id\` (string, required): The time entry ID to update
  - \`project_id\` (string, optional): Change to different project
  - \`task_id\` (string, optional): Change to different task  
  - \`spent_date\` (string, optional): Change date (YYYY-MM-DD)
  - \`hours\` (number, optional): Update hours worked
  - \`notes\` (string, optional): Update notes/description
  
  ## Example Usage
  
  **Update hours and notes:**
  \`\`\`json
  {
    "tool": "harvest_update_time_entry",
    "id": "98765",
    "hours": 3.25,
    "notes": "Completed API integration and testing"
  }
  \`\`\`
  
  **Move entry to different project/task:**
  \`\`\`json
  {
    "tool": "harvest_update_time_entry",
    "id": "98765",
    "project_id": "54321",
    "task_id": "09876",
    "notes": "Moved to correct project"
  }
  \`\`\`
  
  **Change date:**
  \`\`\`json
  {
    "tool": "harvest_update_time_entry",
    "id": "98765", 
    "spent_date": "2024-01-19"
  }
  \`\`\`
  
  ## Response Format
  Returns the updated time entry object with all current values.
  
  ## Notes
  - Cannot update a running timer's hours (stop timer first)
  - Only provide parameters you want to change
  - Use harvest_list_time_entries to find entry IDs`,
  
        'harvest_delete_time_entry': `# harvest_delete_time_entry
  
  Permanently deletes a time entry from your Harvest account.
  
  ## Purpose
  Remove a time entry that was created in error or is no longer needed.
  
  ## Parameters
  - \`id\` (string, required): The time entry ID to delete
  
  ## Example Usage
  
  **Delete a time entry:**
  \`\`\`json
  {
    "tool": "harvest_delete_time_entry",
    "id": "98765"
  }
  \`\`\`
  
  ## Response Format
  Returns a confirmation message: "Time entry {id} deleted successfully"
  
  ## ⚠️ Warning
  This action is permanent and cannot be undone. The time entry will be completely removed from your Harvest account.
  
  ## Workflow Tips
  - Use harvest_list_time_entries to find the entry ID
  - Consider using harvest_update_time_entry to modify instead of delete
  - Verify the entry ID before deletion`,
  
        'harvest_restart_timer': `# harvest_restart_timer
  
  Restarts a stopped time entry timer to resume time tracking.
  
  ## Purpose
  Resume timing on a previously stopped time entry, setting is_running to true and timer_started_at to current time.
  
  ## Parameters
  - \`id\` (string, required): The time entry ID to restart
  
  ## Example Usage
  
  **Restart a stopped timer:**
  \`\`\`json
  {
    "tool": "harvest_restart_timer",
    "id": "98765"
  }
  \`\`\`
  
  ## Response Format
  Returns the updated time entry with:
  - \`is_running\`: true
  - \`timer_started_at\`: Current timestamp
  - \`hours\`: Previous accumulated hours
  - All other time entry properties
  
  ## Requirements
  - Time entry must exist
  - Timer must not already be running
  - Only one timer can run at a time per user
  
  ## Workflow
  1. Find stopped entry: harvest_list_time_entries
  2. Restart timer: harvest_restart_timer  
  3. Work on the task
  4. Stop when done: harvest_stop_timer
  
  ## Error Conditions
  - Entry not found: Invalid ID
  - Timer already running: Cannot restart running timer
  - Another timer running: Stop other timer first`,
  
        'harvest_stop_timer': `# harvest_stop_timer
  
  Stops a running time entry timer and calculates total hours.
  
  ## Purpose
  Stop timing on a running time entry, setting is_running to false and calculating final hours based on elapsed time.
  
  ## Parameters  
  - \`id\` (string, required): The time entry ID to stop
  
  ## Example Usage
  
  **Stop a running timer:**
  \`\`\`json
  {
    "tool": "harvest_stop_timer",
    "id": "98765"
  }
  \`\`\`
  
  ## Response Format
  Returns the updated time entry with:
  - \`is_running\`: false
  - \`timer_started_at\`: null
  - \`hours\`: Calculated total hours including this session
  - \`started_time\`, \`ended_time\`: Session boundaries
  - All other time entry properties
  
  ## Automatic Calculations
  - Hours are automatically calculated from timer duration
  - Previous hours (if any) are added to new session time
  - Time is rounded to your account's time rounding settings
  
  ## Workflow
  1. Start work: harvest_create_time_entry (without hours) or harvest_restart_timer
  2. Work on the task  
  3. Stop timing: harvest_stop_timer
  4. Optionally update notes: harvest_update_time_entry
  
  ## Error Conditions
  - Entry not found: Invalid ID
  - Timer not running: Cannot stop a stopped timer`,
  
        'harvest_list_projects': `# harvest_list_projects
  
  Lists all projects in your Harvest account with filtering options.
  
  ## Purpose
  Retrieve project information for time entry creation, reporting, and project management.
  
  ## Parameters
  - \`is_active\` (boolean, optional): Filter by active/inactive status
  - \`client_id\` (string, optional): Filter by specific client ID
  - \`page\` (number, optional): Page number for pagination
  - \`per_page\` (number, optional): Results per page, max 100
  
  ## Example Usage
  
  **List all active projects:**
  \`\`\`json
  {
    "tool": "harvest_list_projects",
    "is_active": true
  }
  \`\`\`
  
  **List projects for specific client:**
  \`\`\`json
  {
    "tool": "harvest_list_projects", 
    "client_id": "12345",
    "is_active": true
  }
  \`\`\`
  
  **List all projects with pagination:**
  \`\`\`json
  {
    "tool": "harvest_list_projects",
    "page": 1,
    "per_page": 25
  }
  \`\`\`
  
  ## Response Format
  Returns an object with:
  - \`projects\`: Array of project objects
  - Pagination information (per_page, total_pages, etc.)
  
  Each project includes: id, name, code, is_active, client info, budget info, hourly rates, created/updated dates.
  
  ## Usage in Workflows
  - Essential for harvest_create_time_entry (need project_id)
  - Use with harvest_list_task_assignments to get valid tasks
  - Filter by client or active status to find relevant projects`,
  
        'harvest_get_project': `# harvest_get_project
  
  Retrieves detailed information about a specific project.
  
  ## Purpose
  Get comprehensive details about a single project including budget, rates, and client information.
  
  ## Parameters
  - \`id\` (string, required): The project ID to retrieve
  
  ## Example Usage
  
  **Get project details:**
  \`\`\`json
  {
    "tool": "harvest_get_project",
    "id": "12345"
  }
  \`\`\`
  
  ## Response Format
  Returns detailed project object with:
  - Basic info: id, name, code, notes
  - Status: is_active, is_billable, is_fixed_fee
  - Client: full client object
  - Budget: budget, budget_by, budget_is_monthly
  - Rates: hourly_rate, cost_budget, cost_budget_include_expenses
  - Dates: starts_on, ends_on, created_at, updated_at
  - Settings: bill_by, fee, over_budget_notification_percentage
  
  ## Usage Tips
  - Use harvest_list_projects first to find project IDs
  - Useful for checking project status before creating time entries
  - Contains budget information for project tracking`,
  
        'harvest_list_tasks': `# harvest_list_tasks
  
  Lists all tasks available in your Harvest account.
  
  ## Purpose
  Retrieve task information needed for creating time entries and understanding work categories.
  
  ## Parameters
  - \`is_active\` (boolean, optional): Filter by active/inactive status
  - \`page\` (number, optional): Page number for pagination
  - \`per_page\` (number, optional): Results per page, max 100
  
  ## Example Usage
  
  **List all active tasks:**
  \`\`\`json
  {
    "tool": "harvest_list_tasks",
    "is_active": true
  }
  \`\`\`
  
  **List all tasks with pagination:**
  \`\`\`json
  {
    "tool": "harvest_list_tasks",
    "page": 1,
    "per_page": 50
  }
  \`\`\`
  
  ## Response Format
  Returns an object with:
  - \`tasks\`: Array of task objects
  - Pagination information
  
  Each task includes: id, name, billable_by_default, is_active, is_default, hourly_rate, created_at, updated_at.
  
  ## Important Notes
  - Tasks are global but must be assigned to projects
  - Use harvest_list_task_assignments to see which tasks are available for a specific project
  - Not all tasks are valid for all projects`,
  
        'harvest_get_current_user': `# harvest_get_current_user
  
  Retrieves information about the currently authenticated user.
  
  ## Purpose
  Get details about your user account, permissions, and settings.
  
  ## Parameters
  None required.
  
  ## Example Usage
  
  **Get current user info:**
  \`\`\`json
  {
    "tool": "harvest_get_current_user"
  }
  \`\`\`
  
  ## Response Format
  Returns user object with:
  - Basic info: id, first_name, last_name, email
  - Status: is_active, is_admin, is_contractor
  - Settings: timezone, has_access_to_all_future_projects
  - Rates: default_hourly_rate, cost_rate
  - Capacity: weekly_capacity
  - Profile: telephone, avatar_url
  - Dates: created_at, updated_at
  
  ## Usage Tips
  - Useful for confirming authentication is working
  - Check permissions (is_admin, has_access_to_all_future_projects)
  - Get user_id for filtering time entries`,
  
        'harvest_list_users': `# harvest_list_users
  
  Lists all users in your Harvest account.
  
  ## Purpose
  Retrieve information about all users for reporting, filtering, and user management.
  
  ## Parameters
  - \`is_active\` (boolean, optional): Filter by active/inactive status
  - \`page\` (number, optional): Page number for pagination
  - \`per_page\` (number, optional): Results per page, max 100
  
  ## Example Usage
  
  **List all active users:**
  \`\`\`json
  {
    "tool": "harvest_list_users",
    "is_active": true
  }
  \`\`\`
  
  **List all users with pagination:**
  \`\`\`json
  {
    "tool": "harvest_list_users",
    "page": 1,
    "per_page": 25
  }
  \`\`\`
  
  ## Response Format
  Returns an object with:
  - \`users\`: Array of user objects
  - Pagination information
  
  Each user includes same fields as harvest_get_current_user.
  
  ## Usage Tips
  - Use for filtering time entries by user_id
  - Useful for team management and reporting
  - Check user roles and permissions`,
  
        'harvest_list_clients': `# harvest_list_clients
  
  Lists all clients in your Harvest account.
  
  ## Purpose
  Retrieve client information for project filtering, reporting, and client management.
  
  ## Parameters
  - \`is_active\` (boolean, optional): Filter by active/inactive status
  - \`page\` (number, optional): Page number for pagination
  - \`per_page\` (number, optional): Results per page, max 100
  
  ## Example Usage
  
  **List all active clients:**
  \`\`\`json
  {
    "tool": "harvest_list_clients",
    "is_active": true
  }
  \`\`\`
  
  **List all clients:**
  \`\`\`json
  {
    "tool": "harvest_list_clients"
  }
  \`\`\`
  
  ## Response Format
  Returns an object with:
  - \`clients\`: Array of client objects
  - Pagination information
  
  Each client includes: id, name, is_active, address, currency, created_at, updated_at.
  
  ## Usage Tips  
  - Use client_id to filter projects with harvest_list_projects
  - Essential for client-based reporting and organization
  - Useful for understanding account structure`,
  
        'harvest_time_report': `# harvest_time_report
  
  Generates detailed time reports for specified date ranges.
  
  ## Purpose
  Create comprehensive time reports for analysis, billing, and project tracking.
  
  ## Parameters
  - \`from\` (string, optional): Start date in YYYY-MM-DD format
  - \`to\` (string, optional): End date in YYYY-MM-DD format
  - \`user_id\` (string, optional): Filter by specific user
  - \`project_id\` (string, optional): Filter by specific project
  - \`client_id\` (string, optional): Filter by specific client
  - \`page\` (number, optional): Page number for pagination
  - \`per_page\` (number, optional): Results per page, max 100
  
  ## Example Usage
  
  **Monthly report for current month:**
  \`\`\`json
  {
    "tool": "harvest_time_report",
    "from": "2024-01-01",
    "to": "2024-01-31"
  }
  \`\`\`
  
  **User-specific report:**
  \`\`\`json
  {
    "tool": "harvest_time_report",
    "from": "2024-01-15", 
    "to": "2024-01-21",
    "user_id": "12345"
  }
  \`\`\`
  
  **Project report:**
  \`\`\`json
  {
    "tool": "harvest_time_report",
    "from": "2024-01-01",
    "to": "2024-01-31",
    "project_id": "67890"
  }
  \`\`\`
  
  ## Response Format
  Returns object with:
  - \`results\`: Array of time report entries
  - Pagination and summary information
  
  Each result includes: user_id, user_name, total_hours, billable_hours, billable_amount, currency info.
  
  ## Report Types
  - Team time reports (default)
  - User-specific reports (with user_id)
  - Project-specific reports (with project_id)
  - Client-specific reports (with client_id)
  
  ## Usage Tips
  - Use date ranges for specific periods
  - Combine filters for targeted reports
  - Results are paginated for large datasets`,
  
        'harvest_list_project_assignments': `# harvest_list_project_assignments
  
  Lists project assignments for the current user.
  
  ## Purpose
  See which projects you have access to and can log time against.
  
  ## Parameters
  - \`page\` (number, optional): Page number for pagination
  - \`per_page\` (number, optional): Results per page, max 100
  
  ## Example Usage
  
  **List your project assignments:**
  \`\`\`json
  {
    "tool": "harvest_list_project_assignments"
  }
  \`\`\`
  
  **With pagination:**
  \`\`\`json
  {
    "tool": "harvest_list_project_assignments",
    "page": 1,
    "per_page": 25
  }
  \`\`\`
  
  ## Response Format
  Returns object with:
  - \`project_assignments\`: Array of assignment objects
  - Pagination information
  
  Each assignment includes:
  - \`id\`: Assignment ID
  - \`project\`: Full project object  
  - \`client\`: Full client object
  - \`hourly_rate\`: Your rate for this project
  - \`budget\`: Budget information
  - \`is_active\`: Assignment status
  - \`created_at\`, \`updated_at\`: Timestamps
  
  ## Usage Tips
  - Essential for finding valid project_id values for time entries
  - Shows your specific hourly rate per project
  - Use with harvest_list_task_assignments to get complete assignment info`,
  
        'harvest_list_task_assignments': `# harvest_list_task_assignments
  
  Lists task assignments for a specific project.
  
  ## Purpose
  See which tasks are available for time tracking on a specific project.
  
  ## Parameters
  - \`project_id\` (string, required): The project ID to get task assignments for
  - \`page\` (number, optional): Page number for pagination
  - \`per_page\` (number, optional): Results per page, max 100
  
  ## Example Usage
  
  **List task assignments for a project:**
  \`\`\`json
  {
    "tool": "harvest_list_task_assignments",
    "project_id": "12345"
  }
  \`\`\`
  
  **With pagination:**
  \`\`\`json
  {
    "tool": "harvest_list_task_assignments",
    "project_id": "12345",
    "page": 1,
    "per_page": 50
  }
  \`\`\`
  
  ## Response Format
  Returns object with:
  - \`task_assignments\`: Array of task assignment objects  
  - Pagination information
  
  Each assignment includes:
  - \`id\`: Assignment ID
  - \`task\`: Full task object with name, rates
  - \`is_active\`: Assignment status
  - \`billable\`: Whether task is billable
  - \`hourly_rate\`: Rate for this task on this project
  - \`budget\`: Budget allocation for this task
  - \`created_at\`, \`updated_at\`: Timestamps
  
  ## Workflow
  1. Use harvest_list_project_assignments to find projects
  2. Use harvest_list_task_assignments to find valid tasks
  3. Use project_id and task_id for harvest_create_time_entry
  
  ## Notes
  - Only shows tasks that are actually assigned to the project
  - Each project-task combination has its own assignment
  - Required for getting valid task_id values for time entries`
      };
  
      return toolDetails[toolName] || `Tool "${toolName}" not found. Available tools: ${Object.keys(toolDetails).join(', ')}`;
    }