get_teams

Instructions

Implementation Reference

• src/pagerduty_mcp_server/server.py:500-527 (handler)

  The main MCP tool handler for 'get_teams'. Registered via @mcp.tool() decorator. Delegates to teams.show_team() if team_id is provided, otherwise calls teams.list_teams().

  @mcp.tool()
  @tool_error_boundary
  @validation.validate_include_parameter(Team)
  async def get_teams(
      *,
      team_id: Optional[str] = None,
      query: Optional[str] = None,
      limit: Optional[int] = None,
      include: Optional[List[str]] = None,
  ) -> Dict[str, Any]:
      """Get PagerDuty teams by filters or get details for a specific team ID.
  
      Args:
          team_id (str): The team ID to retrieve (optional, cannot be used with any other filters).
          query (str): Filter teams whose names contain the search query (optional). Not used if `team_id` is provided.
          limit (int): Limit the number of results returned (optional). Not used if `team_id` is provided.
          include (List[str]): List of fields to include in the response. If specified, only these fields will be returned for each team
      """
      if team_id is not None:
          disallowed_filters_present = query is not None or limit is not None
          if disallowed_filters_present:
              raise ValueError(
                  "When `team_id` is provided, other filters (like query, limit) cannot be used. See `docs://tools` for more information."
              )
  
          return await teams.show_team(team_id=team_id, include=include)
  
      return await teams.list_teams(query=query, limit=limit, include=include)

• src/pagerduty_mcp_server/teams.py:60-100 (schema)

  Helper function that fetches a single team by ID via the PagerDuty API. Used by get_teams when team_id is provided.

  async def show_team(
      *, team_id: str, include: Optional[List[str]] = None
  ) -> Dict[str, Any]:
      """Get detailed information about a given team. Exposed as MCP server tool.
  
      Args:
          team_id (str): The ID of the team to get
          include (List[str]): List of fields to include in the response. If specified, only these fields will be returned for the team
  
      Returns:
          See the "Standard Response Format" section in `tools.md` for the complete standard response structure.
          The response will contain a single team with detailed configuration and member information.
  
      Raises:
          See the "Error Handling" section in `tools.md` for common error scenarios.
      """
  
      if team_id is None:
          raise ValueError("team_id must be specified")
  
      pd_client = create_client()
  
      try:
          response = await safe_execute_async(
              lambda: pd_client.jget(f"{TEAMS_URL}/{team_id}"), f"fetch team {team_id}"
          )
          try:
              team_data = response["team"]
          except KeyError:
              raise RuntimeError(
                  f"Failed to fetch team {team_id}: Response missing 'team' field"
              )
  
          parsed_team = {}
          if team_data:
              model = Team.model_validate(team_data)
              parsed_team = model.to_clean_dict(include_fields=include)
  
          return utils.api_response_handler(results=parsed_team, resource_name="team")
      except Exception as e:
          utils.handle_api_error(e)

• src/pagerduty_mcp_server/teams.py:20-57 (schema)

  Helper function that lists teams via the PagerDuty API with optional query/limit/include filters. Used by get_teams when no team_id is provided.

  async def list_teams(
      *,
      query: Optional[str] = None,
      limit: Optional[int] = None,
      include: Optional[List[str]] = None,
  ) -> Dict[str, Any]:
      """List teams in your PagerDuty account. Exposed as MCP server tool.
  
      Args:
          query (str): Filter teams whose names contain the search query (optional)
          limit (int): Limit the number of results returned (optional)
          include (List[str]): List of fields to include in the response. If specified, only these fields will be returned for each team
  
      Returns:
          See the "Standard Response Format" section in `tools.md` for the complete standard response structure.
          The response will contain a list of teams with their configuration and member information.
  
      Raises:
          See the "Error Handling" section in `tools.md` for common error scenarios.
      """
  
      pd_client = create_client()
  
      params = {}
      if query:
          params["query"] = query
  
      try:
          response = await paginate(
              pd_client,
              TEAMS_URL,
              params=params,
              max_records=limit or DEFAULT_MAX_RESULTS,
              operation_name="list teams",
          )
          return utils.parse_list_response(response, Team, "teams", include=include)
      except Exception as e:
          utils.handle_api_error(e)

• src/pagerduty_mcp_server/server.py:500-503 (registration)

  The @mcp.tool() decorator on line 500 registers 'get_teams' as an MCP tool with the FastMCP server instance.

  @mcp.tool()
  @tool_error_boundary
  @validation.validate_include_parameter(Team)
  async def get_teams(

• src/pagerduty_mcp_server/teams.py:108-125 (helper)

  Internal helper that extracts team IDs from a user dictionary. Used by other modules, not directly by get_teams.

  def fetch_team_ids(*, user: Dict[str, Any]) -> List[str]:
      """Get the team IDs for a user. Internal helper function.
  
      Args:
          user (Dict[str, Any]): The user object containing a teams field with team information
  
      Returns:
          List[str]: A list of team IDs from the user's teams. Returns an empty list if user is None or has no teams.
  
      Note:
          This is an internal helper function used by other modules to extract team IDs from a user object.
          It should not be called directly by external code.
  
      Raises:
          KeyError: If user is None or missing the 'teams' field
      """
  
      return [team["id"] for team in user["teams"]]