MCP Fathom Analytics

Instructions

Implementation Reference

• src/tools/events.ts:13-50 (handler)

  The handler function for the 'list-events' tool. It fetches all events for a given Fathom Analytics site_id (with optional limit), handles pagination internally via fathomClient.api.getAllEvents, formats the events as text, and returns them in the MCP response format. Includes error handling.

  async ({ site_id, limit }) => {
      try {
          const events = await fathomClient.api.getAllEvents(site_id, limit);
          
          if (events.length === 0) {
              return {
                  content: [
                      {
                          type: "text",
                          text: `No events found for site ${site_id}.`,
                      },
                  ],
              };
          }
  
          const eventsText = events.map(event => 
              `ID: ${event.id}\nName: ${event.name}\nCreated: ${event.created_at}\n`
          ).join("\n---\n\n");
          
          return {
              content: [
                  {
                      type: "text",
                      text: `All events for site ${site_id} (${events.length}):\n\n${eventsText}`,
                  },
              ],
          };
      } catch (error) {
          return {
              content: [
                  {
                      type: "text",
                      text: `Failed to retrieve events: ${error instanceof FathomApiError ? `${error.status}: ${error.error}` : String(error)}`,
                  },
              ],
          };
      }
  },

• src/tools/events.ts:9-12 (schema)

  Input schema for the 'list-events' tool using Zod: requires site_id (string), optional limit (positive number). Descriptions provided.

  {
      site_id: z.string().describe("ID of the site to retrieve events for"),
      limit: z.number().positive().optional().describe("Optional limit on the number of events to return")
  },

• src/tools/events.ts:6-51 (registration)

  Registration of the 'list-events' tool via server.tool() call inside the registerEventsTool function, including name, description, schema, and handler.

  server.tool(
      "list-events",
      "List all events for a Fathom Analytics site (automatically handles pagination)",
      {
          site_id: z.string().describe("ID of the site to retrieve events for"),
          limit: z.number().positive().optional().describe("Optional limit on the number of events to return")
      },
      async ({ site_id, limit }) => {
          try {
              const events = await fathomClient.api.getAllEvents(site_id, limit);
              
              if (events.length === 0) {
                  return {
                      content: [
                          {
                              type: "text",
                              text: `No events found for site ${site_id}.`,
                          },
                      ],
                  };
              }
  
              const eventsText = events.map(event => 
                  `ID: ${event.id}\nName: ${event.name}\nCreated: ${event.created_at}\n`
              ).join("\n---\n\n");
              
              return {
                  content: [
                      {
                          type: "text",
                          text: `All events for site ${site_id} (${events.length}):\n\n${eventsText}`,
                      },
                  ],
              };
          } catch (error) {
              return {
                  content: [
                      {
                          type: "text",
                          text: `Failed to retrieve events: ${error instanceof FathomApiError ? `${error.status}: ${error.error}` : String(error)}`,
                      },
                  ],
              };
          }
      },
  );