whmcs-mcp-server

Instructions

Implementation Reference

• src/index.ts:220-237 (registration)

  Registration of the whmcs_get_products MCP tool, including input schema, description, and thin wrapper handler that delegates to WhmcsApiClient.getProducts

  server.registerTool(
      'whmcs_get_products',
      {
          title: 'Get Products',
          description: 'Get available products/services from WHMCS',
          inputSchema: {
              pid: z.number().optional().describe('Specific product ID'),
              gid: z.number().optional().describe('Filter by product group ID'),
              module: z.string().optional().describe('Filter by server module'),
          },
      },
      async (params) => {
          const result = await whmcsClient.getProducts(params);
          return {
              content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
          };
      }
  );

• src/whmcs-client.ts:347-385 (handler)

  Core handler implementation in WhmcsApiClient that executes the WHMCS 'GetProducts' API action via the generic call method

  /**
   * Get products
   */
  async getProducts(params: {
      pid?: number;
      gid?: number;
      module?: string;
  } = {}) {
      return this.call<WhmcsApiResponse & {
          totalresults: number;
          startnumber: number;
          numreturned: number;
          products: { product: Array<{
              pid: number;
              gid: number;
              type: string;
              name: string;
              description: string;
              module: string;
              paytype: string;
              pricing: Record<string, {
                  prefix: string;
                  suffix: string;
                  msetupfee: string;
                  qsetupfee: string;
                  ssetupfee: string;
                  asetupfee: string;
                  bsetupfee: string;
                  tsetupfee: string;
                  monthly: string;
                  quarterly: string;
                  semiannually: string;
                  annually: string;
                  biennially: string;
                  triennially: string;
              }>;
          }> };
      }>('GetProducts', params);
  }

• src/index.ts:225-229 (schema)

  Zod input schema defining parameters for the whmcs_get_products tool: optional pid, gid, and module filters

  inputSchema: {
      pid: z.number().optional().describe('Specific product ID'),
      gid: z.number().optional().describe('Filter by product group ID'),
      module: z.string().optional().describe('Filter by server module'),
  },

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

  Generic API client method used by getProducts and all other WHMCS API calls to handle authentication, request formatting, 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;
  }