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)}`,
                    },
                ],
            };
        }
    },
);

MCP Fathom Analytics