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; }