Clicky MCP Server

Instructions

Implementation Reference

• src/tools/get-domain-visitors.ts:43-74 (handler)

  The main handler function that executes the tool's logic: parses input arguments, constructs DateRange, calls the ClickyClient's getDomainVisitors method, formats the JSON response, and handles errors.

  export async function handleGetDomainVisitors(
    args: { domain: string; start_date: string; end_date: string; segments?: string[]; limit?: number },
    clickyClient: ClickyClient
  ) {
    try {
      const dateRange: DateRange = {
        startDate: args.start_date,
        endDate: args.end_date
      };
  
      const data = await clickyClient.getDomainVisitors(args.domain, dateRange, args.segments, args.limit);
  
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify(data, null, 2)
          }
        ]
      };
    } catch (error) {
      return {
        content: [
          {
            type: 'text',
            text: `Error fetching domain visitors: ${error instanceof Error ? error.message : 'Unknown error'}`
          }
        ],
        isError: true
      };
    }
  }

• src/tools/get-domain-visitors.ts:4-41 (schema)

  The tool definition object including the input schema for validating tool call parameters: domain (required), start_date/end_date (YYYY-MM-DD required), optional segments (pages/visitors), and limit.

  export const getDomainVisitorsTool: Tool = {
    name: 'get_domain_visitors',
    description: 'Get visitors filtered by domain from Clicky analytics with optional segmentation data',
    inputSchema: {
      type: 'object',
      properties: {
        domain: {
          type: 'string',
          description: 'Domain name to filter by (e.g., "facebook.com", "google.com")'
        },
        start_date: {
          type: 'string',
          pattern: '^\\d{4}-\\d{2}-\\d{2}$',
          description: 'Start date in YYYY-MM-DD format'
        },
        end_date: {
          type: 'string',
          pattern: '^\\d{4}-\\d{2}-\\d{2}$',
          description: 'End date in YYYY-MM-DD format'
        },
        segments: {
          type: 'array',
          items: {
            type: 'string',
            enum: ['pages', 'visitors']
          },
          description: 'Optional array of segments to include (pages, visitors). Defaults to visitors only. "visitors" gets the total number of visitors from the domain. "pages" get the list of pages and its visited count from the domain.'
        },
        limit: {
          type: 'number',
          minimum: 1,
          maximum: 1000,
          description: 'Optional limit for results (max 1000)'
        }
      },
      required: ['domain', 'start_date', 'end_date']
    }
  };

• src/index.ts:91-99 (registration)

  Registration of the getDomainVisitorsTool in the list of available tools for the ListToolsRequestHandler.

  this.server.setRequestHandler(ListToolsRequestSchema, async () => ({
    tools: [
      getTotalVisitorsTool,
      getDomainVisitorsTool,
      getTopPagesTool,
      getTrafficSourcesTool,
      getPageTrafficTool,
    ],
  }));

• src/index.ts:109-110 (registration)

  Dispatch/registration of the handler for 'get_domain_visitors' tool calls in the CallToolRequestHandler switch statement.

  case 'get_domain_visitors':
    return await handleGetDomainVisitors(args as any, this.clickyClient);

• src/clicky-client.ts:60-80 (helper)

  Supporting ClickyClient method that performs the actual API request to fetch domain visitors data using segmentation endpoint.

  async getDomainVisitors(domain: string, dateRange: DateRange, segments?: string[], limit?: number): Promise<any> {
    this.validateDateRange(dateRange);
  
    const params: any = {
      site_id: this.siteId,
      sitekey: this.siteKey,
      type: 'segmentation',
      domain: domain,
      segments: segments ? segments.join(',') : 'visitors',
      date: `${dateRange.startDate},${dateRange.endDate}`,
      output: 'json'
    };
  
    if (limit) {
      params.limit = Math.min(limit, 1000); // API max is 1000
    }
  
    const response = await this.client.get('', { params });
  
    return response.data;
  }