harvest-mcp-server

Instructions

Implementation Reference

• src/tools/invoices.ts:58-74 (handler)

  The CreateInvoiceHandler class responsible for executing the create_invoice tool logic by validating inputs and interacting with the Harvest API client.

  class CreateInvoiceHandler implements ToolHandler {
    constructor(private readonly config: BaseToolConfig) {}
  
    async execute(args: Record<string, any>): Promise<CallToolResult> {
      try {
        const validatedArgs = validateInput(CreateInvoiceSchema, args, 'create invoice');
        logger.info('Creating invoice via Harvest API');
        const invoice = await this.config.harvestClient.createInvoice(validatedArgs);
        
        return {
          content: [{ type: 'text', text: JSON.stringify(invoice, null, 2) }],
        };
      } catch (error) {
        return handleMCPToolError(error, 'create_invoice');
      }
    }
  }

• src/tools/invoices.ts:152-176 (registration)

  Registration of the create_invoice tool in the registerInvoiceTools function, including its name, description, and input schema.

  {
    tool: {
      name: 'create_invoice',
      description: 'Create a new invoice for a client with optional line items and billing details. Supports custom terms, taxes, and payment configurations.',
      inputSchema: {
        type: 'object',
        properties: {
          client_id: { type: 'number', description: 'The client ID to invoice (required)' },
          subject: { type: 'string', description: 'Invoice subject line' },
          notes: { type: 'string', description: 'Invoice notes or description' },
          currency: { type: 'string', minLength: 3, maxLength: 3, description: '3-letter ISO currency code (e.g., USD, EUR)' },
          issue_date: { type: 'string', format: 'date', description: 'Invoice issue date (YYYY-MM-DD)' },
          due_date: { type: 'string', format: 'date', description: 'Invoice due date (YYYY-MM-DD)' },
          payment_term: { type: 'string', description: 'Payment terms (e.g., "Net 30")' },
          tax: { type: 'number', minimum: 0, maximum: 100, description: 'Tax percentage (0-100)' },
          tax2: { type: 'number', minimum: 0, maximum: 100, description: 'Second tax percentage (0-100)' },
          discount: { type: 'number', minimum: 0, maximum: 100, description: 'Discount percentage (0-100)' },
          purchase_order: { type: 'string', description: 'Client purchase order number' },
        },
        required: ['client_id'],
        additionalProperties: false,
      },
    },
    handler: new CreateInvoiceHandler(config),
  },