whmcs-mcp-server

Instructions

Implementation Reference

• src/whmcs-client.ts:302-341 (handler)

  Core handler implementation: Makes WHMCS API call to 'GetClientsDomains' action, handling parameters and response typing for client domains.

  /**
   * Get client's domains
   */
  async getClientDomains(params: {
      clientid?: number;
      domainid?: number;
      domain?: string;
      limitstart?: number;
      limitnum?: number;
  } = {}) {
      return this.call<WhmcsApiResponse & {
          totalresults: number;
          startnumber: number;
          numreturned: number;
          domains: { domain: Array<{
              id: number;
              userid: number;
              orderid: number;
              regtype: string;
              domainname: string;
              registrar: string;
              regperiod: number;
              firstpaymentamount: string;
              recurringamount: string;
              paymentmethod: string;
              paymentmethodname: string;
              regdate: string;
              expirydate: string;
              nextduedate: string;
              status: string;
              subscriptionid: string;
              promoid: number;
              dnsmanagement: string;
              emailforwarding: string;
              idprotection: string;
              donotrenew: string;
              notes: string;
          }> };
      }>('GetClientsDomains', params);
  }

• src/index.ts:195-214 (registration)

  Tool registration with MCP server, including input schema validation using Zod and thin async handler wrapper that delegates to WhmcsApiClient.getClientDomains.

  server.registerTool(
      'whmcs_get_client_domains',
      {
          title: 'Get Client Domains',
          description: 'Get domains owned by a client',
          inputSchema: {
              clientid: z.number().optional().describe('The client ID'),
              domainid: z.number().optional().describe('Specific domain ID'),
              domain: z.string().optional().describe('Filter by domain name'),
              limitstart: z.number().optional().describe('Starting offset'),
              limitnum: z.number().optional().describe('Number of results'),
          },
      },
      async (params) => {
          const result = await whmcsClient.getClientDomains(params);
          return {
              content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
          };
      }
  );

• src/index.ts:198-206 (schema)

  Zod input schema definition for tool parameters: client ID, domain ID, domain filter, pagination.

  title: 'Get Client Domains',
  description: 'Get domains owned by a client',
  inputSchema: {
      clientid: z.number().optional().describe('The client ID'),
      domainid: z.number().optional().describe('Specific domain ID'),
      domain: z.string().optional().describe('Filter by domain name'),
      limitstart: z.number().optional().describe('Starting offset'),
      limitnum: z.number().optional().describe('Number of results'),
  },

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

  Generic API call helper used by all methods including getClientDomains: constructs POST request to WHMCS API, flattens params, handles auth and errors.

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