whmcs-mcp-server

Instructions

Implementation Reference

• src/whmcs-client.ts:454-501 (handler)

  The core handler function that makes the WHMCS API call to retrieve detailed invoice information using the 'GetInvoice' action.

  async getInvoice(params: { invoiceid: number }) {
      return this.call<WhmcsApiResponse & {
          invoiceid: number;
          invoicenum: string;
          userid: number;
          date: string;
          duedate: string;
          datepaid: string;
          status: string;
          paymentmethod: string;
          paymethodid: string | null;
          subtotal: string;
          credit: string;
          tax: string;
          tax2: string;
          total: string;
          balance: string;
          taxrate: string;
          taxrate2: string;
          currencycode: string;
          currencyprefix: string;
          currencysuffix: string;
          notes: string;
          ccgateway: boolean;
          items: { item: Array<{
              id: number;
              type: string;
              relid: number;
              description: string;
              amount: string;
              taxed: number;
          }> };
          transactions: { transaction: Array<{
              id: number;
              userid: number;
              currency: number;
              gateway: string;
              date: string;
              description: string;
              amountin: string;
              amountout: string;
              rate: string;
              transid: string;
              invoiceid: number;
              refundid: number;
          }> };
      }>('GetInvoice', params);
  }

• src/index.ts:280-295 (registration)

  Registers the 'whmcs_get_invoice' tool with MCP server, including schema validation using Zod and the thin wrapper handler.

  server.registerTool(
      'whmcs_get_invoice',
      {
          title: 'Get Invoice Details',
          description: 'Get detailed information about a specific invoice',
          inputSchema: {
              invoiceid: z.number().describe('The invoice ID'),
          },
      },
      async (params) => {
          const result = await whmcsClient.getInvoice(params);
          return {
              content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
          };
      }
  );

• src/index.ts:285-287 (schema)

  Zod schema for input validation: requires invoiceid as a number.

  inputSchema: {
      invoiceid: z.number().describe('The invoice ID'),
  },

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

  The generic API call method used by getInvoice to communicate with WHMCS API, including param flattening and error handling.

  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;
  }