PagerDuty MCP Server

Instructions

Implementation Reference

• src/pagerduty_mcp_server/server.py:296-338 (handler)

  The handler function for the 'get_services' MCP tool. It performs input validation, resolves user context if needed, and delegates to appropriate helper functions for listing or showing services.

  @mcp.tool()
  def get_services(
      *,
      service_id: Optional[str] = None,
      current_user_context: bool = True,
      team_ids: Optional[List[str]] = None,
      query: Optional[str] = None,
      limit: Optional[int] = None,
  ) -> Dict[str, Any]:
      """Get PagerDuty services by filters or get details for a specific service ID.
  
      Args:
          service_id (str): The service ID to retrieve (optional, cannot be used with any other filters).
          current_user_context (bool): Use current user's team IDs to filter (default: True). Not used if `service_id` is provided.
          team_ids (List[str]): Filter results to only services assigned to teams with the given IDs (optional, cannot be used with current_user_context). Not used if `service_id` is provided.
          query (str): Filter services whose names contain the search query (optional). Not used if `service_id` is provided.
          limit (int): Limit the number of results (optional). Not used if `service_id` is provided.
      """
      if service_id is not None:
          disallowed_filters_present = (
              team_ids is not None or query is not None or limit is not None
          )
          if disallowed_filters_present:
              raise ValueError(
                  "When `service_id` is provided, other filters (like team_ids, query, limit) cannot be used. See `docs://tools` for more information."
              )
  
          return services.show_service(service_id=service_id)
  
      if current_user_context:
          if team_ids is not None:
              raise ValueError(
                  "Cannot specify team_ids when current_user_context is True. See `docs://tools` for more information."
              )
          user_context = users.build_user_context()
          team_ids = user_context["team_ids"]
      elif not team_ids:
          raise ValueError(
              "Must specify at least team_ids when current_user_context is False. See `docs://tools` for more information."
          )
  
      return services.list_services(team_ids=team_ids, query=query, limit=limit)

• src/pagerduty_mcp_server/services.py:19-63 (helper)

  Helper function that lists PagerDuty services based on team_ids, query, and limit filters. Called by the get_services handler.

  def list_services(
      *,
      team_ids: Optional[List[str]] = None,
      query: Optional[str] = None,
      limit: Optional[int] = None,
  ) -> Dict[str, Any]:
      """List existing PagerDuty services. Exposed as MCP server tool.
  
      Args:
          team_ids (List[str]): Filter results to only services assigned to teams with the given IDs (optional)
          query (str): Filter services whose names contain the search query (optional)
          limit (int): Limit the number of results returned (optional)
  
      Returns:
          See the "Standard Response Format" section in `tools.md` for the complete standard response structure.
          The response will contain a list of services with their configuration and team assignments.
  
      Raises:
          See the "Error Handling" section in `tools.md` for common error scenarios.
      """
  
      pd_client = create_client()
  
      if team_ids is not None and not team_ids:
          raise ValueError("team_ids cannot be an empty list")
  
      params = {}
      if team_ids:
          params["team_ids[]"] = (
              team_ids  # PagerDuty API expects array parameters with [] suffix
          )
      if query:
          params["query"] = query
      if limit:
          params["limit"] = limit
  
      try:
          response = pd_client.list_all(SERVICES_URL, params=params)
          parsed_response = [parse_service(result=result) for result in response]
          return utils.api_response_handler(
              results=parsed_response, resource_name="services"
          )
      except Exception as e:
          utils.handle_api_error(e)

• src/pagerduty_mcp_server/services.py:65-98 (helper)

  Helper function that retrieves detailed information for a specific PagerDuty service by ID. Called by the get_services handler.

  def show_service(*, service_id: str) -> Dict[str, Any]:
      """Get detailed information about a given service. Exposed as MCP server tool.
  
      Args:
          service_id (str): The ID of the service to get
  
      Returns:
          See the "Standard Response Format" section in `tools.md` for the complete standard response structure.
          The response will contain a single service with detailed configuration and team information.
  
      Raises:
          See the "Error Handling" section in `tools.md` for common error scenarios.
      """
  
      if not service_id:
          raise ValueError("service_id cannot be empty")
  
      pd_client = create_client()
  
      try:
          response = pd_client.jget(f"{SERVICES_URL}/{service_id}")
          try:
              service_data = response["service"]
          except KeyError:
              raise RuntimeError(
                  f"Failed to fetch service {service_id}: Response missing 'service' field"
              )
  
          return utils.api_response_handler(
              results=parse_service(result=service_data), resource_name="service"
          )
      except Exception as e:
          utils.handle_api_error(e)