event_list

Instructions

Implementation Reference

• src/tools/events.ts:131-152 (handler)

  The _handleTool private method routes 'event_list' to call this.api.getEvents(args) and returns formatted or raw event data. This is the core handler logic for the event_list tool.

  private async _handleTool(name: string, args: any) {
    switch (name) {
      case 'event_list':
        console.error(`Fetching events with params:`, args);
        const events = await this.api.getEvents(args);
        console.error(`Retrieved ${events.rows?.length || 0} events`);
        if (args.raw) {
          return {
            content: [{
              type: "text",
              text: JSON.stringify(events.rows.slice(0, 20), null, 2)
            }]
          };
        }
        const formattedEvents = events.rows.slice(0,20).map(formatEvent).join('\n');
        console.error(formattedEvents);
        return {
          content: [{
            type: "text",
            text: formattedEvents
          }]
        };

• src/tools/events.ts:36-67 (schema)

  The inputSchema for event_list defines parameters: limit, offset, startdate, enddate, raw, and optionally appName when using master key.

  inputSchema: {
    type: "object",
    properties: {
      limit: { 
        type: "number", 
        description: "Maximum number of events to return (default: 100)" 
      },
      offset: { 
        type: "number", 
        description: "Number of events to skip for pagination" 
      },
      startdate: {
        type: "string",
        description: "Filter events after this date (ISO format, e.g. 2024-01-01)"
      },
      enddate: {
        type: "string",
        description: "Filter events before this date (ISO format, e.g. 2024-12-31)"
      },
      raw: {
        type: "boolean",
        description: "Return raw JSON instead of formatted output (default: false)"
      },
      ...(appNameRequired ? {
        appName: {
          type: "string",
          description: "Name of the app to fetch data from. Required when using master key."
        }
      } : {})
    },
    required: appNameRequired ? ["appName"] : undefined
  }

• src/tools/events.ts:24-68 (registration)

  The tool is registered with name 'event_list' in the getTools() method of the EventTools class, which returns tool definitions for MCP.

        {
          name: "event_list",
          description: `List recent events from your Iaptic account.
  - Returns a paginated list of system events
  - Events include:
    - Receipt validations
    - Platform notifications (Apple/Google/etc)
    - Webhook deliveries
    - Purchase status changes
    - Subscription renewals
  - Use limit and offset for pagination
  - Results ordered by date (newest first)${appNameRequired ? '\n- Requires appName parameter when using master key' : ''}`,
          inputSchema: {
            type: "object",
            properties: {
              limit: { 
                type: "number", 
                description: "Maximum number of events to return (default: 100)" 
              },
              offset: { 
                type: "number", 
                description: "Number of events to skip for pagination" 
              },
              startdate: {
                type: "string",
                description: "Filter events after this date (ISO format, e.g. 2024-01-01)"
              },
              enddate: {
                type: "string",
                description: "Filter events before this date (ISO format, e.g. 2024-12-31)"
              },
              raw: {
                type: "boolean",
                description: "Return raw JSON instead of formatted output (default: false)"
              },
              ...(appNameRequired ? {
                appName: {
                  type: "string",
                  description: "Name of the app to fetch data from. Required when using master key."
                }
              } : {})
            },
            required: appNameRequired ? ["appName"] : undefined
          }
        },

• src/server.ts:68-81 (registration)

  The ListToolsRequestSchema handler collects all tools via getTools() and the CallToolRequestSchema handler routes 'event_' prefixed names to events.handleTool(). This is how the tool is wired into the MCP server.

  private setupHandlers() {
    // List available tools
    this.server.setRequestHandler(ListToolsRequestSchema, async () => {
      return {
        tools: [
          ...this.tools.customers.getTools(),
          ...this.tools.purchases.getTools(),
          ...this.tools.transactions.getTools(),
          ...this.tools.statistics.getTools(),
          ...this.tools.stripe.getTools(),
          ...this.tools.events.getTools(),
          ...this.tools.app.getTools()
        ]
      };

• src/tools/events.ts:179-219 (helper)

  The formatEvent helper function formats a single IapticEvent into a human-readable string, used in the non-raw path of event_list.

  function formatEvent(event: IapticEvent): string {
    const { context, content } = event;
    const { transactions, products, refreshFailures } = content;
  
    // Start with basic event info
    let output = `### ${new Date(context.eventDate).toLocaleString()}: ${context.eventType} by ${context.applicationUsername || 'system'}`;
    output += `\n  eventId: ${event.eventId}`;
  
    // Flag errors from tags (dashboard equivalent: content.tags.error === "_X")
    if (content.tags?.error) {
      output += `\n  [ERROR] Use event_details for error info`;
    }
  
    // Add refresh failures if present
    if (refreshFailures?.length > 0) {
      output += '\nRefresh Failures:';
      output += refreshFailures.map(f => `\n  ${f.platform}: ${f.reason}`).join('');
    }
  
    // Format transaction info with more details
    if (transactions?.length > 0) {
      output += '\nTransactions:';
      output += transactions.map(t =>
        `\n  ${t.transactionId}: ${t.productId}${t.amountMicros ? ` (${(t.amountMicros/1000000).toFixed(2)} ${t.currency})` : ''}`
        + `${t.sandbox ? ' [SANDBOX]' : ''}`
        + `${t.isConsumed ? ' [CONSUMED]' : ''}`
        + `${t.isAcknowledged ? ' [ACKNOWLEDGED]' : ''}`
      ).join('');
    }
  
    // Add product info if present
    if (products?.length > 0) {
      output += '\nProducts:';
      output += products.map(p =>
        `\n  ${p.id} (${p.type})${p.offers?.[0]?.pricingPhases?.[0]?.priceMicros ?
          ` - ${(p.offers[0].pricingPhases[0].priceMicros/1000000).toFixed(2)} ${p.currency}` : ''}`
      ).join('');
    }
  
    return output;
  }