Clicky MCP Server

Instructions

Implementation Reference

• src/tools/get-total-visitors.ts:25-56 (handler)

  The main handler function for the get_total_visitors tool. Converts input dates to DateRange, calls ClickyClient.getTotalVisitors, formats the JSON response or error.

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

• src/tools/get-total-visitors.ts:7-22 (schema)

  Input schema for the get_total_visitors tool, validating start_date and end_date as YYYY-MM-DD strings.

  inputSchema: {
    type: 'object',
    properties: {
      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'
      }
    },
    required: ['start_date', 'end_date']
  }

• src/tools/get-total-visitors.ts:4-23 (registration)

  Tool definition and export for get_total_visitors, including name, description, and input schema.

  export const getTotalVisitorsTool: Tool = {
    name: 'get_total_visitors',
    description: 'Get total visitors for a date range from Clicky analytics',
    inputSchema: {
      type: 'object',
      properties: {
        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'
        }
      },
      required: ['start_date', 'end_date']
    }
  };

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

  Registration of getTotalVisitorsTool in the ListToolsRequest handler.

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

• src/index.ts:106-107 (registration)

  Dispatch registration in the CallToolRequest switch statement for get_total_visitors.

  case 'get_total_visitors':
    return await handleGetTotalVisitors(args as any, this.clickyClient);

• src/clicky-client.ts:44-58 (helper)

  ClickyClient helper method that performs the actual API request to Clicky for total visitors data.

  async getTotalVisitors(dateRange: DateRange): Promise<any> {
    this.validateDateRange(dateRange);
  
    const response = await this.client.get('', {
      params: {
        site_id: this.siteId,
        sitekey: this.siteKey,
        type: 'visitors',
        date: `${dateRange.startDate},${dateRange.endDate}`,
        output: 'json'
      }
    });
  
    return response.data;
  }