Clicky MCP Server

Instructions

Implementation Reference

• src/tools/get-page-traffic.ts:29-60 (handler)

  The main handler function that processes the get_page_traffic tool call, constructs date range, calls the ClickyClient helper, formats JSON response or error.

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

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

  Tool definition with input schema specifying required parameters: url (string), start_date and end_date (YYYY-MM-DD strings with pattern validation).

  export const getPageTrafficTool: Tool = {
    name: 'get_page_traffic',
    description: 'Get traffic data for a specific page by filtering with its URL',
    inputSchema: {
      type: 'object',
      properties: {
        url: {
          type: 'string',
          description: 'Full URL or path of the page to get traffic for (e.g., https://example.com/path or /path)'
        },
        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: ['url', 'start_date', 'end_date']
    }
  };

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

  Registration in listToolsRequestHandler: getPageTrafficTool is included in the array of available tools advertised to MCP clients.

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

• src/index.ts:118-119 (registration)

  Dispatch in callToolRequestHandler switch: routes calls to 'get_page_traffic' to the specific handleGetPageTraffic function.

  case 'get_page_traffic':
    return await handleGetPageTraffic(args as any, this.clickyClient);

• src/clicky-client.ts:136-164 (helper)

  ClickyClient helper method that queries the Clicky API 'pages' endpoint with filter=path to retrieve traffic data for the specific page.

  async getPageTraffic(url: string, dateRange: DateRange): Promise<any> {
    this.validateDateRange(dateRange);
  
    // Extract path from URL and encode it
    let path: string;
    try {
      const urlObj = new URL(url);
      path = urlObj.pathname;
    } catch (error) {
      // If URL parsing fails, assume it's already a path
      path = url.startsWith('/') ? url : '/' + url;
    }
  
    // Use raw path - Axios will handle the URL encoding automatically
    const filterPath = path;
  
    const response = await this.client.get('', {
      params: {
        site_id: this.siteId,
        sitekey: this.siteKey,
        type: 'pages',
        filter: filterPath,
        date: `${dateRange.startDate},${dateRange.endDate}`,
        output: 'json'
      }
    });
  
    return response.data;
  }