Clicky MCP Server

Instructions

Implementation Reference

• src/tools/get-top-pages.ts:31-62 (handler)

  The handler function that implements the core logic of the 'get_top_pages' tool. It parses the input arguments, calls the ClickyClient's getTopPages method, and returns the formatted response or error.

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

• src/tools/get-top-pages.ts:4-29 (schema)

  The tool definition object for 'get_top_pages' including the input schema for validation of parameters like start_date, end_date, and optional limit.

  export const getTopPagesTool: Tool = {
    name: 'get_top_pages',
    description: 'Get top pages 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'
        },
        limit: {
          type: 'number',
          minimum: 1,
          maximum: 1000,
          description: 'Maximum number of pages to return (default: API default, max: 1000)'
        }
      },
      required: ['start_date', 'end_date']
    }
  };

• src/index.ts:92-98 (registration)

  Registration of the getTopPagesTool in the listTools handler, making it discoverable by MCP clients.

  tools: [
    getTotalVisitorsTool,
    getDomainVisitorsTool,
    getTopPagesTool,
    getTrafficSourcesTool,
    getPageTrafficTool,
  ],

• src/index.ts:112-113 (registration)

  Registration of the handler dispatch for 'get_top_pages' in the callTool request switch statement.

  case 'get_top_pages':
    return await handleGetTopPages(args as any, this.clickyClient);

• src/clicky-client.ts:82-99 (helper)

  Supporting method in ClickyClient that performs the actual API call to retrieve top pages data from Clicky analytics.

  async getTopPages(dateRange: DateRange, limit?: number): Promise<any> {
    this.validateDateRange(dateRange);
  
    const params: any = {
      site_id: this.siteId,
      sitekey: this.siteKey,
      type: 'pages',
      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;
  }