whmcs-mcp-server

Instructions

Implementation Reference

• src/index.ts:454-480 (registration)

  Registration of the 'whmcs_open_ticket' MCP tool, including schema, title, description, and thin wrapper handler that delegates to WhmcsApiClient.openTicket

  server.registerTool(
      'whmcs_open_ticket',
      {
          title: 'Open Ticket',
          description: 'Create a new support ticket',
          inputSchema: {
              deptid: z.number().describe('Department ID'),
              subject: z.string().describe('Ticket subject'),
              message: z.string().describe('Ticket message/description'),
              clientid: z.number().optional().describe('Client ID'),
              contactid: z.number().optional().describe('Contact ID'),
              name: z.string().optional().describe('Name (if not a client)'),
              email: z.string().optional().describe('Email (if not a client)'),
              priority: z.enum(['Low', 'Medium', 'High']).optional().describe('Ticket priority'),
              serviceid: z.number().optional().describe('Related service ID'),
              domainid: z.number().optional().describe('Related domain ID'),
              admin: z.boolean().optional().describe('Opened by admin'),
              markdown: z.boolean().optional().describe('Message contains markdown'),
          },
      },
      async (params) => {
          const result = await whmcsClient.openTicket(params);
          return {
              content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
          };
      }
  );

• src/whmcs-client.ts:704-725 (handler)

  Core handler implementation in WhmcsApiClient: openTicket method that makes the WHMCS API call to 'OpenTicket' action

  async openTicket(params: {
      deptid: number;
      subject: string;
      message: string;
      clientid?: number;
      contactid?: number;
      name?: string;
      email?: string;
      priority?: 'Low' | 'Medium' | 'High';
      serviceid?: number;
      domainid?: number;
      admin?: boolean;
      markdown?: boolean;
      attachments?: Array<{ name: string; data: string }>;
      customfields?: string;
  }) {
      return this.call<WhmcsApiResponse & {
          id: number;
          tid: string;
          c: string;
      }>('OpenTicket', params);
  }

• src/index.ts:460-472 (schema)

  Zod input schema validation for the whmcs_open_ticket tool parameters

      deptid: z.number().describe('Department ID'),
      subject: z.string().describe('Ticket subject'),
      message: z.string().describe('Ticket message/description'),
      clientid: z.number().optional().describe('Client ID'),
      contactid: z.number().optional().describe('Contact ID'),
      name: z.string().optional().describe('Name (if not a client)'),
      email: z.string().optional().describe('Email (if not a client)'),
      priority: z.enum(['Low', 'Medium', 'High']).optional().describe('Ticket priority'),
      serviceid: z.number().optional().describe('Related service ID'),
      domainid: z.number().optional().describe('Related domain ID'),
      admin: z.boolean().optional().describe('Opened by admin'),
      markdown: z.boolean().optional().describe('Message contains markdown'),
  },

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

  WhmcsApiClient.call method: core utility that performs HTTP POST to WHMCS API endpoint, handles auth, flattening params, error checking, used by all API methods including openTicket

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