whmcs-mcp-server

Instructions

Implementation Reference

• src/whmcs-client.ts:503-524 (handler)

  The createInvoice method in WhmcsApiClient that implements the tool logic by calling the WHMCS 'CreateInvoice' API action using the generic HTTP client.

  /**
   * Create an invoice
   */
  async createInvoice(params: {
      userid: number;
      status?: 'Draft' | 'Unpaid' | 'Paid' | 'Cancelled' | 'Refunded' | 'Collections';
      sendinvoice?: boolean;
      paymentmethod?: string;
      taxrate?: number;
      taxrate2?: number;
      date?: string;
      duedate?: string;
      notes?: string;
      itemdescription?: string[];
      itemamount?: number[];
      itemtaxed?: boolean[];
  }) {
      return this.call<WhmcsApiResponse & {
          invoiceid: number;
          status: string;
      }>('CreateInvoice', params);
  }

• src/index.ts:297-323 (registration)

  Registers the whmcs_create_invoice tool with the MCP server, including title, description, Zod input schema for validation, and thin async handler delegating to whmcsClient.createInvoice.

  server.registerTool(
      'whmcs_create_invoice',
      {
          title: 'Create Invoice',
          description: 'Create a new invoice for a client',
          inputSchema: {
              userid: z.number().describe('Client ID'),
              status: z.enum(['Draft', 'Unpaid', 'Paid', 'Cancelled', 'Refunded', 'Collections']).optional().describe('Invoice status'),
              sendinvoice: z.boolean().optional().describe('Send invoice email'),
              paymentmethod: z.string().optional().describe('Payment method'),
              taxrate: z.number().optional().describe('Tax rate percentage'),
              taxrate2: z.number().optional().describe('Second tax rate percentage'),
              date: z.string().optional().describe('Invoice date (YYYY-MM-DD)'),
              duedate: z.string().optional().describe('Due date (YYYY-MM-DD)'),
              notes: z.string().optional().describe('Invoice notes'),
              itemdescription: z.array(z.string()).optional().describe('Line item descriptions'),
              itemamount: z.array(z.number()).optional().describe('Line item amounts'),
              itemtaxed: z.array(z.boolean()).optional().describe('Line items taxed flags'),
          },
      },
      async (params) => {
          const result = await whmcsClient.createInvoice(params);
          return {
              content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
          };
      }
  );

• src/index.ts:302-316 (schema)

  Zod schema defining the input parameters and validation for the whmcs_create_invoice tool, matching WHMCS CreateInvoice API requirements.

      inputSchema: {
          userid: z.number().describe('Client ID'),
          status: z.enum(['Draft', 'Unpaid', 'Paid', 'Cancelled', 'Refunded', 'Collections']).optional().describe('Invoice status'),
          sendinvoice: z.boolean().optional().describe('Send invoice email'),
          paymentmethod: z.string().optional().describe('Payment method'),
          taxrate: z.number().optional().describe('Tax rate percentage'),
          taxrate2: z.number().optional().describe('Second tax rate percentage'),
          date: z.string().optional().describe('Invoice date (YYYY-MM-DD)'),
          duedate: z.string().optional().describe('Due date (YYYY-MM-DD)'),
          notes: z.string().optional().describe('Invoice notes'),
          itemdescription: z.array(z.string()).optional().describe('Line item descriptions'),
          itemamount: z.array(z.number()).optional().describe('Line item amounts'),
          itemtaxed: z.array(z.boolean()).optional().describe('Line items taxed flags'),
      },
  },

• src/whmcs-client.ts:29-63 (helper)

  Generic API client method used by createInvoice to send authenticated POST requests to WHMCS API, handles param flattening, error checking, and JSON response parsing.

  async call<T extends WhmcsApiResponse>(action: string, params: Record<string, unknown> = {}): Promise<T> {
      const url = `${this.config.apiUrl.replace(/\/$/, '')}/includes/api.php`;
      
      const postData: Record<string, string> = {
          identifier: this.config.apiIdentifier,
          secret: this.config.apiSecret,
          action: action,
          responsetype: 'json',
          ...this.flattenParams(params)
      };
  
      if (this.config.accessKey) {
          postData.accesskey = this.config.accessKey;
      }
  
      const response = await fetch(url, {
          method: 'POST',
          headers: {
              'Content-Type': 'application/x-www-form-urlencoded',
          },
          body: new URLSearchParams(postData).toString(),
      });
  
      if (!response.ok) {
          throw new Error(`WHMCS API request failed: ${response.status} ${response.statusText}`);
      }
  
      const data = await response.json() as T;
      
      if (data.result === 'error') {
          throw new Error(`WHMCS API error: ${data.message || 'Unknown error'}`);
      }
  
      return data;
  }