list_meetings

Instructions

Implementation Reference

• tools/meetings.py:45-113 (handler)

  Core handler function that executes the tool logic: builds API parameters using helper, calls Fathom API to list meetings with filters, handles pagination and errors.

  async def list_meetings(
      ctx: Context,
      calendar_invitees: Optional[List[str]] = None,
      calendar_invitees_domains: Optional[List[str]] = None,
      created_after: Optional[str] = None,
      created_before: Optional[str] = None,
      cursor: Optional[str] = None,
      include_action_items: Optional[bool] = None,
      include_crm_matches: Optional[bool] = None,
      recorded_by: Optional[List[str]] = None,
      teams: Optional[List[str]] = None,
      per_page: Optional[int] = None
  ) -> dict:
      """Retrieve paginated list of meetings with optional filtering and content inclusion.
      
      Returns meeting records with metadata, optionally including action items and CRM matches.
      Use recording_id from results to fetch individual recording content including summaries.
      
      Args:
          ctx: MCP context for logging
          calendar_invitees: List of email addresses to filter meetings by attendees
          calendar_invitees_domains: List of domains to filter meetings by attendee domains
          created_after: ISO 8601 timestamp (e.g., "2024-01-01T00:00:00Z") - meetings created after this time
          created_before: ISO 8601 timestamp (e.g., "2024-12-31T23:59:59Z") - meetings created before this time
          cursor: Pagination cursor from previous response for next page
          include_action_items: Set True to include action items in response
          include_crm_matches: Set True to include CRM match data in response
          recorded_by: List of email addresses to filter by meeting recorder
          teams: List of team names to filter meetings by associated teams
          per_page: Number of results per page (default: 50, configurable via DEFAULT_PER_PAGE env var)
      
      Returns:
          dict: {
              "items": [Meeting objects with fields like title, url, created_at, recording_id, etc.],
              "limit": int (default 20),
              "cursor": str (for pagination, null if no more results)
          }
      """
      try:
          await ctx.info("Fetching meetings from Fathom API")
  
          # Use config default if per_page not provided
          effective_per_page = per_page if per_page is not None else config.default_per_page
  
          # Build parameters
          params = _build_meetings_params(
              calendar_invitees=calendar_invitees,
              calendar_invitees_domains=calendar_invitees_domains,
              created_after=created_after,
              created_before=created_before,
              cursor=cursor,
              include_action_items=include_action_items,
              include_crm_matches=include_crm_matches,
              recorded_by=recorded_by,
              teams=teams,
              per_page=effective_per_page
          )
  
          result = await client.get_meetings(params=params if params else None)
          await ctx.info("Successfully retrieved meetings")
  
          return result
  
      except FathomAPIError as e:
          await ctx.error(f"Fathom API error: {e.message}")
          raise e
      except Exception as e:
          await ctx.error(f"Unexpected error fetching meetings: {str(e)}")
          raise e

• server.py:106-152 (registration)

  MCP tool registration using @mcp.tool decorator. Defines input schema with Pydantic Field descriptions and defaults. Thin wrapper that delegates to the core implementation in tools/meetings.py.

  @mcp.tool
  async def list_meetings(
      ctx: Context,
      calendar_invitees: list[str] = Field(
          default=None, description="Filter by invitee emails"
      ),
      calendar_invitees_domains: list[str] = Field(
          default=None, description="Filter by domains"
      ),
      created_after: str = Field(default=None, description="ISO timestamp filter"),
      created_before: str = Field(default=None, description="ISO timestamp filter"),
      cursor: str = Field(default=None, description="Pagination cursor"),
      include_action_items: bool = Field(
          default=None, description="Include action items"
      ),
      include_crm_matches: bool = Field(default=None, description="Include CRM matches"),
      per_page: int = Field(
          default=config.default_per_page,
          description=f"Number of results per page (default: {config.default_per_page})",
      ),
      recorded_by: list[str] = Field(
          default=None, description="Filter by recorder emails"
      ),
      teams: list[str] = Field(default=None, description="Filter by team names"),
  ) -> Dict[str, Any]:
      """Retrieve paginated meetings with filtering and optional content inclusion (action items, CRM matches).
      
      Examples:
          list_meetings()  # Get all meetings (paginated)
          list_meetings(created_after="2024-01-01T00:00:00Z")  # Meetings after specific date
          list_meetings(teams=["Sales", "Engineering"])  # Filter by specific teams
          list_meetings(calendar_invitees=["john.doe@company.com", "jane.smith@client.com"])  # Filter by specific attendees
          list_meetings(calendar_invitees_domains=["company.com", "client.com"])  # Filter by attendee domains
      """
      return await tools.meetings.list_meetings(
          ctx,
          calendar_invitees=calendar_invitees,
          calendar_invitees_domains=calendar_invitees_domains,
          created_after=created_after,
          created_before=created_before,
          cursor=cursor,
          include_action_items=include_action_items,
          include_crm_matches=include_crm_matches,
          per_page=per_page,
          recorded_by=recorded_by,
          teams=teams
      )

• tools/meetings.py:7-43 (helper)

  Supporting utility function that constructs the query parameters dictionary for the Fathom API call based on provided filters.

  def _build_meetings_params(
      calendar_invitees: Optional[List[str]] = None,
      calendar_invitees_domains: Optional[List[str]] = None,
      created_after: Optional[str] = None,
      created_before: Optional[str] = None,
      cursor: Optional[str] = None,
      include_action_items: Optional[bool] = None,
      include_crm_matches: Optional[bool] = None,
      recorded_by: Optional[List[str]] = None,
      teams: Optional[List[str]] = None,
      per_page: Optional[int] = None
  ) -> dict:
      """Build API parameters dict from function arguments"""
      params = {}
      
      if calendar_invitees:
          params["calendar_invitees[]"] = calendar_invitees
      if calendar_invitees_domains:
          params["calendar_invitees_domains[]"] = calendar_invitees_domains
      if created_after:
          params["created_after"] = created_after
      if created_before:
          params["created_before"] = created_before
      if cursor:
          params["cursor"] = cursor
      if include_action_items is not None:
          params["include_action_items"] = include_action_items
      if include_crm_matches is not None:
          params["include_crm_matches"] = include_crm_matches
      if recorded_by:
          params["recorded_by[]"] = recorded_by
      if teams:
          params["teams[]"] = teams
      if per_page is not None:
          params["limit"] = per_page
      
      return params

• tools/meetings.py:58-82 (schema)

  Detailed docstring defining input parameters, their descriptions, and output schema for the list_meetings tool.

  """Retrieve paginated list of meetings with optional filtering and content inclusion.
  
  Returns meeting records with metadata, optionally including action items and CRM matches.
  Use recording_id from results to fetch individual recording content including summaries.
  
  Args:
      ctx: MCP context for logging
      calendar_invitees: List of email addresses to filter meetings by attendees
      calendar_invitees_domains: List of domains to filter meetings by attendee domains
      created_after: ISO 8601 timestamp (e.g., "2024-01-01T00:00:00Z") - meetings created after this time
      created_before: ISO 8601 timestamp (e.g., "2024-12-31T23:59:59Z") - meetings created before this time
      cursor: Pagination cursor from previous response for next page
      include_action_items: Set True to include action items in response
      include_crm_matches: Set True to include CRM match data in response
      recorded_by: List of email addresses to filter by meeting recorder
      teams: List of team names to filter meetings by associated teams
      per_page: Number of results per page (default: 50, configurable via DEFAULT_PER_PAGE env var)
  
  Returns:
      dict: {
          "items": [Meeting objects with fields like title, url, created_at, recording_id, etc.],
          "limit": int (default 20),
          "cursor": str (for pagination, null if no more results)
      }
  """