get-current-visitors
Retrieve real-time visitor data for a Fathom Analytics site, including optional content and referrer details for current traffic monitoring.
Instructions
Get current visitors for a Fathom Analytics site
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| site_id | Yes | ID of the site to retrieve current visitors for | |
| detailed | No | Whether to include detailed content and referrer information |
Implementation Reference
- src/tools/visitors.ts:13-67 (handler)The asynchronous handler function that executes the tool logic: fetches current visitors from Fathom API based on site_id and optional detailed flag, formats the response as markdown text blocks, handles no visitors and errors.
async ({ site_id, detailed = false }) => { try { const visitorsData = await fathomClient.api.reports.currentVisitors({ site_id, detailed }); if (visitorsData.total === 0) { return { content: [ { type: "text", text: `No current visitors for site ${site_id}.`, }, ], }; } let responseText = `Current visitors for site ${site_id}: ${visitorsData.total}\n\n`; // Include detailed information if available and requested if (detailed && visitorsData.content && visitorsData.content.length > 0) { responseText += "Top Content:\n"; visitorsData.content.forEach((item, index) => { responseText += `${index + 1}. ${item.hostname}${item.pathname} - ${item.total} visitor(s)\n`; }); responseText += "\n"; } if (detailed && visitorsData.referrers && visitorsData.referrers.length > 0) { responseText += "Top Referrers:\n"; visitorsData.referrers.forEach((item, index) => { responseText += `${index + 1}. ${item.referrer_hostname}${item.referrer_pathname} - ${item.total} visitor(s)\n`; }); } return { content: [ { type: "text", text: responseText, }, ], }; } catch (error) { return { content: [ { type: "text", text: `Failed to retrieve current visitors: ${error instanceof FathomApiError ? `${error.status}: ${error.error}` : String(error)}`, }, ], }; } }, - src/tools/visitors.ts:10-12 (schema)Zod input schema defining parameters: required site_id (string) and optional detailed (boolean).
site_id: z.string().describe("ID of the site to retrieve current visitors for"), detailed: z.boolean().optional().describe("Whether to include detailed content and referrer information"), }, - src/tools/visitors.ts:6-68 (registration)MCP server.tool() registration of the 'get-current-visitors' tool, including name, description, input schema, and handler function.
server.tool( "get-current-visitors", "Get current visitors for a Fathom Analytics site", { site_id: z.string().describe("ID of the site to retrieve current visitors for"), detailed: z.boolean().optional().describe("Whether to include detailed content and referrer information"), }, async ({ site_id, detailed = false }) => { try { const visitorsData = await fathomClient.api.reports.currentVisitors({ site_id, detailed }); if (visitorsData.total === 0) { return { content: [ { type: "text", text: `No current visitors for site ${site_id}.`, }, ], }; } let responseText = `Current visitors for site ${site_id}: ${visitorsData.total}\n\n`; // Include detailed information if available and requested if (detailed && visitorsData.content && visitorsData.content.length > 0) { responseText += "Top Content:\n"; visitorsData.content.forEach((item, index) => { responseText += `${index + 1}. ${item.hostname}${item.pathname} - ${item.total} visitor(s)\n`; }); responseText += "\n"; } if (detailed && visitorsData.referrers && visitorsData.referrers.length > 0) { responseText += "Top Referrers:\n"; visitorsData.referrers.forEach((item, index) => { responseText += `${index + 1}. ${item.referrer_hostname}${item.referrer_pathname} - ${item.total} visitor(s)\n`; }); } return { content: [ { type: "text", text: responseText, }, ], }; } catch (error) { return { content: [ { type: "text", text: `Failed to retrieve current visitors: ${error instanceof FathomApiError ? `${error.status}: ${error.error}` : String(error)}`, }, ], }; } }, );