Clicky MCP Server

Instructions

Implementation Reference

• src/tools/get-traffic-sources.ts:29-73 (handler)

  The handler function that processes input arguments, calls the Clicky client to fetch traffic sources, transforms the raw API response into a structured JSON format suitable for LLMs, and handles errors by returning an error response.

  export async function handleGetTrafficSources(
    args: { start_date: string; end_date: string; page_url?: string },
    clickyClient: ClickyClient
  ) {
    try {
      const dateRange: DateRange = {
        startDate: args.start_date,
        endDate: args.end_date
      };
  
      const data = await clickyClient.getTrafficSources(dateRange, args.page_url);
  
      // Transform the response to be LLM-friendly
      const cleanedData = data.map((typeData: any) => ({
        type: typeData.type,
        dates: typeData.dates.map((dateData: any) => ({
          date: dateData.date,
          traffic_sources: dateData.items.map((item: any) => ({
            source: item.title,
            visitors: parseInt(item.value),
            percentage: parseFloat(item.value_percent || '0')
          }))
        }))
      }));
  
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify(cleanedData, null, 2)
          }
        ]
      };
    } catch (error) {
      return {
        content: [
          {
            type: 'text',
            text: `Error fetching traffic sources: ${error instanceof Error ? error.message : 'Unknown error'}`
          }
        ],
        isError: true
      };
    }
  }

• src/tools/get-traffic-sources.ts:4-27 (schema)

  The Tool object definition including the input schema that validates start_date and end_date (required, YYYY-MM-DD format) and optional page_url.

  export const getTrafficSourcesTool: Tool = {
    name: 'get_traffic_sources',
    description: 'Get traffic sources breakdown from Clicky analytics. Optionally filter by specific page URL.',
    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'
        },
        page_url: {
          type: 'string',
          description: 'Optional: Full URL or path of the page to get traffic sources for (e.g., https://example.com/path or /path)'
        }
      },
      required: ['start_date', 'end_date']
    }
  };

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

  Registers the getTrafficSourcesTool in the list of available tools for the ListToolsRequest handler.

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

• src/index.ts:115-116 (registration)

  Registers the handler dispatch for 'get_traffic_sources' in the CallToolRequest switch statement.

  case 'get_traffic_sources':
    return await handleGetTrafficSources(args as any, this.clickyClient);

• src/clicky-client.ts:101-134 (helper)

  Supporting method in ClickyClient that performs the actual API request for traffic sources, using segmentation for page-specific data or general traffic-sources type.

  async getTrafficSources(dateRange: DateRange, pageUrl?: string): Promise<any> {
    this.validateDateRange(dateRange);
  
    let params: any = {
      site_id: this.siteId,
      sitekey: this.siteKey,
      date: `${dateRange.startDate},${dateRange.endDate}`,
      output: 'json'
    };
  
    if (pageUrl) {
      // Extract path from URL and encode it
      let path: string;
      try {
        const urlObj = new URL(pageUrl);
        path = urlObj.pathname;
      } catch (error) {
        // If URL parsing fails, assume it's already a path
        path = pageUrl.startsWith('/') ? pageUrl : '/' + pageUrl;
      }
  
      // Use segmentation API for page-specific traffic sources
      params.type = 'segmentation';
      params.href = path; // Axios will handle the URL encoding automatically
      params.segments = 'traffic-sources';
    } else {
      // Use general traffic sources API
      params.type = 'traffic-sources';
    }
  
    const response = await this.client.get('', { params });
  
    return response.data;
  }