get-referrers
Track and analyze incoming traffic sources for a WordPress site by retrieving detailed referrer data. Specify time period and limit results for precise insights into user origins.
Instructions
View a site's referrers
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of referrers to return | |
| password | Yes | WordPress application password | |
| period | No | Time period for stats | |
| siteId | Yes | WordPress site ID | |
| siteUrl | Yes | WordPress site URL | |
| username | Yes | WordPress username |
Implementation Reference
- src/index.ts:1280-1329 (registration)Registration of the 'get-referrers' tool using server.tool(), including schema and handler.server.tool( "get-referrers", "View a site's referrers", { siteUrl: z.string().url().describe("WordPress site URL"), username: z.string().describe("WordPress username"), password: z.string().describe("WordPress application password"), siteId: z.number().describe("WordPress site ID"), period: z.enum(["day", "week", "month", "year"]).optional().describe("Time period for stats"), limit: z.number().min(1).max(100).optional().describe("Maximum number of referrers to return"), }, async ({ siteUrl, username, password, siteId, period = "week", limit = 10 }) => { try { const referrersData = await makeWPRequest<{referrers: WPReferrer[]}>({ siteUrl, endpoint: `sites/${siteId}/stats/referrers`, auth: { username, password }, params: { period, limit } }); const referrersText = Array.isArray(referrersData.referrers) && referrersData.referrers.length > 0 ? referrersData.referrers.map((ref) => `${ref.name || "Unknown"} (${ref.group || "Unknown Group"}) URL: ${ref.url || "No URL"} Views: ${ref.views || 0} ${ref.is_spam ? "⚠️ Marked as spam" : ""} ---` ).join("\n") : "No referrers found"; return { content: [ { type: "text", text: `Referrers for site #${siteId} (${period}):\n\n${referrersText}`, }, ], }; } catch (error) { return { content: [ { type: "text", text: `Error retrieving referrers: ${error instanceof Error ? error.message : String(error)}`, }, ], }; } } );
- src/index.ts:1291-1328 (handler)Handler function that fetches referrer stats from WordPress Jetpack API endpoint `/sites/{siteId}/stats/referrers` and formats the response as text.async ({ siteUrl, username, password, siteId, period = "week", limit = 10 }) => { try { const referrersData = await makeWPRequest<{referrers: WPReferrer[]}>({ siteUrl, endpoint: `sites/${siteId}/stats/referrers`, auth: { username, password }, params: { period, limit } }); const referrersText = Array.isArray(referrersData.referrers) && referrersData.referrers.length > 0 ? referrersData.referrers.map((ref) => `${ref.name || "Unknown"} (${ref.group || "Unknown Group"}) URL: ${ref.url || "No URL"} Views: ${ref.views || 0} ${ref.is_spam ? "⚠️ Marked as spam" : ""} ---` ).join("\n") : "No referrers found"; return { content: [ { type: "text", text: `Referrers for site #${siteId} (${period}):\n\n${referrersText}`, }, ], }; } catch (error) { return { content: [ { type: "text", text: `Error retrieving referrers: ${error instanceof Error ? error.message : String(error)}`, }, ], }; } }
- src/index.ts:1284-1290 (schema)Zod schema defining input parameters for the get-referrers tool.siteUrl: z.string().url().describe("WordPress site URL"), username: z.string().describe("WordPress username"), password: z.string().describe("WordPress application password"), siteId: z.number().describe("WordPress site ID"), period: z.enum(["day", "week", "month", "year"]).optional().describe("Time period for stats"), limit: z.number().min(1).max(100).optional().describe("Maximum number of referrers to return"), },
- src/index.ts:125-131 (schema)TypeScript interface defining the structure of a WPReferrer object used in the tool's response parsing.interface WPReferrer { group: string; name: string; url: string; views: number; is_spam?: boolean; }
- src/index.ts:158-194 (helper)Shared helper function used by the tool to make authenticated requests to WordPress REST API.async function makeWPRequest<T>({ siteUrl, endpoint, method = 'GET', auth, data = null, params = null }: { siteUrl: string; endpoint: string; method?: 'GET' | 'POST' | 'PUT' | 'DELETE'; auth: { username: string; password: string }; data?: any; params?: any; }): Promise<T> { const authString = Buffer.from(`${auth.username}:${auth.password}`).toString('base64'); try { const response = await axios({ method, url: `${siteUrl}/wp-json/wp/v2/${endpoint}`, headers: { 'Authorization': `Basic ${authString}`, 'Content-Type': 'application/json', }, data: data, params: params }); return response.data as T; } catch (error) { if (axios.isAxiosError(error) && error.response) { throw new Error(`WordPress API error: ${error.response.data?.message || error.message}`); } throw error; } }