get-site-stats
Retrieve detailed WordPress site statistics, including traffic and performance metrics, by providing site URL, username, password, and site ID. Essential for monitoring and analyzing site activity over specific time periods.
Instructions
Get comprehensive stats for a WordPress site
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| 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:1453-1513 (handler)The handler function for the 'get-site-stats' tool. It fetches comprehensive site statistics from the WordPress site's Jetpack Stats API endpoint `/sites/${siteId}/stats`, processes the response to extract key metrics like visits, views, top posts, and top referrers, formats them into a readable text summary, and returns it as MCP content. Uses the shared makeWPRequest helper for the API call.
async ({ siteUrl, username, password, siteId, period = "week" }) => { try { const stats = await makeWPRequest<any>({ siteUrl, endpoint: `sites/${siteId}/stats`, auth: { username, password }, params: { period } }); // Format general site stats - fields will depend on API response let statsText = `Site #${siteId} Stats (${period}):\n\n`; if (stats) { // Add visitors and views if available if (stats.visits) { statsText += `Visitors: ${stats.visits || 0}\n`; } if (stats.views) { statsText += `Views: ${stats.views || 0}\n`; } // Add top posts if available if (stats.top_posts && Array.isArray(stats.top_posts)) { statsText += `\nTop Posts:\n`; statsText += stats.top_posts.slice(0, 5).map((post: any, index: number) => `${index + 1}. "${post.title || "Untitled"}" - ${post.views || 0} views` ).join('\n'); } // Add top referrers if available if (stats.referrers && Array.isArray(stats.referrers)) { statsText += `\n\nTop Referrers:\n`; statsText += stats.referrers.slice(0, 5).map((ref: any) => `${ref.name || "Unknown"}: ${ref.views || 0} views` ).join('\n'); } // Add more sections based on what's available in the API response } else { statsText += "No stats data found."; } return { content: [ { type: "text", text: statsText, }, ], }; } catch (error) { return { content: [ { type: "text", text: `Error retrieving site stats: ${error instanceof Error ? error.message : String(error)}`, }, ], }; } } - src/index.ts:1444-1514 (registration)The registration of the 'get-site-stats' tool on the MCP server, specifying the tool name, description, Zod input schema for parameters (siteUrl, username, password, siteId, optional period), and linking to the handler function.
"get-site-stats", "Get comprehensive stats for a WordPress site", { 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"), }, async ({ siteUrl, username, password, siteId, period = "week" }) => { try { const stats = await makeWPRequest<any>({ siteUrl, endpoint: `sites/${siteId}/stats`, auth: { username, password }, params: { period } }); // Format general site stats - fields will depend on API response let statsText = `Site #${siteId} Stats (${period}):\n\n`; if (stats) { // Add visitors and views if available if (stats.visits) { statsText += `Visitors: ${stats.visits || 0}\n`; } if (stats.views) { statsText += `Views: ${stats.views || 0}\n`; } // Add top posts if available if (stats.top_posts && Array.isArray(stats.top_posts)) { statsText += `\nTop Posts:\n`; statsText += stats.top_posts.slice(0, 5).map((post: any, index: number) => `${index + 1}. "${post.title || "Untitled"}" - ${post.views || 0} views` ).join('\n'); } // Add top referrers if available if (stats.referrers && Array.isArray(stats.referrers)) { statsText += `\n\nTop Referrers:\n`; statsText += stats.referrers.slice(0, 5).map((ref: any) => `${ref.name || "Unknown"}: ${ref.views || 0} views` ).join('\n'); } // Add more sections based on what's available in the API response } else { statsText += "No stats data found."; } return { content: [ { type: "text", text: statsText, }, ], }; } catch (error) { return { content: [ { type: "text", text: `Error retrieving site stats: ${error instanceof Error ? error.message : String(error)}`, }, ], }; } } ); - src/index.ts:1446-1452 (schema)The Zod schema defining the input parameters for the 'get-site-stats' tool: required site URL, credentials, site ID, and optional time period (day/week/month/year).
{ 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"), }, - src/index.ts:158-194 (helper)The makeWPRequest helper function used by the get-site-stats handler (and other tools) to perform authenticated HTTP requests to WordPress REST API endpoints using axios and Basic Auth.
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; } }