PagerDuty MCP Server

Instructions

Implementation Reference

• src/pagerduty_mcp_server/server.py:245-273 (handler)

  Handler function for the 'get_schedules' tool. Dispatches to list_schedules or show_schedule helpers based on whether a specific schedule_id is provided. Includes input validation and documentation.

  @mcp.tool()
  def get_schedules(
      *,
      schedule_id: Optional[str] = None,
      query: Optional[str] = None,
      limit: Optional[int] = None,
      since: Optional[str] = None,
      until: Optional[str] = None,
  ) -> Dict[str, Any]:
      """Get PagerDuty schedules by filters or get details for a specific schedule ID.
  
      Args:
          schedule_id (str): The schedule ID to retrieve details for (optional, cannot be used with query or limit).
          query (str): Filter schedules whose names contain the search query (optional). Not used if `schedule_id` is provided.
          limit (int): Limit the number of results returned (optional). Not used if `schedule_id` is provided.
          since (str): Start time for overrides/final schedule details (ISO8601, optional). Only used if `schedule_id` is provided. Defaults to 2 weeks before 'until' if 'until' is given.
          until (str): End time for overrides/final schedule details (ISO8601, optional). Only used if `schedule_id` is provided. Defaults to 2 weeks after 'since' if 'since' is given.
      """
      if schedule_id is not None:
          if query is not None or limit is not None:
              raise ValueError(
                  "When `schedule_id` is provided, other filters (query, limit) cannot be used. See `docs://tools` for more information."
              )
          return schedules.show_schedule(
              schedule_id=schedule_id, since=since, until=until
          )
      else:
          return schedules.list_schedules(query=query, limit=limit)

• src/pagerduty_mcp_server/schedules.py:19-52 (helper)

  Helper function called by get_schedules to list schedules matching the query and limit parameters using the PagerDuty API.

  def list_schedules(
      *, query: Optional[str] = None, limit: Optional[int] = None
  ) -> Dict[str, Any]:
      """List existing PagerDuty schedules. Returns all schedules that match the given search criteria. Exposed in `get_schedules`.
  
      Args:
          query (str): Filter schedules 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 schedules with their configuration and team assignments.
  
      Raises:
          See the "Error Handling" section in `tools.md` for common error scenarios.
      """
  
      pd_client = create_client()
  
      params = {}
      if query:
          params["query"] = query
      if limit:
          params["limit"] = limit
  
      try:
          response = pd_client.list_all(SCHEDULES_URL, params=params)
          parsed_response = [parse_schedule(result=result) for result in response]
          return utils.api_response_handler(
              results=parsed_response, resource_name="schedules"
          )
      except Exception as e:
          utils.handle_api_error(e)

• src/pagerduty_mcp_server/schedules.py:54-99 (helper)

  Helper function called by get_schedules to retrieve detailed information for a specific schedule, including overrides over a time range, using the PagerDuty API.

  def show_schedule(
      *, schedule_id: str, since: Optional[str] = None, until: Optional[str] = None
  ) -> Dict[str, Any]:
      """Get detailed information about a given schedule, including its configuration and current state. Exposed in `get_schedules`.
  
      Args:
          schedule_id (str): The ID of the schedule to get
          since (str): Start of date range in ISO8601 format (optional). Default is 1 month ago
          until (str): End of date range in ISO8601 format (optional). Default is now
  
      Returns:
          See the "Standard Response Format" section in `tools.md` for the complete standard response structure.
          The response will contain a single schedule with detailed configuration and team information.
  
      Raises:
          See the "Error Handling" section in `tools.md` for common error scenarios.
      """
  
      if not schedule_id:
          raise ValueError("schedule_id cannot be empty")
  
      pd_client = create_client()
  
      params = {}
      if since:
          utils.validate_iso8601_timestamp(since, "since")
          params["since"] = since
      if until:
          utils.validate_iso8601_timestamp(until, "until")
          params["until"] = until
  
      try:
          response = pd_client.jget(f"{SCHEDULES_URL}/{schedule_id}", params=params)
          try:
              schedule_data = response["schedule"]
          except KeyError:
              raise RuntimeError(
                  f"Failed to fetch schedule {schedule_id}: Response missing 'schedule' field"
              )
  
          return utils.api_response_handler(
              results=parse_schedule(result=schedule_data), resource_name="schedule"
          )
      except Exception as e:
          utils.handle_api_error(e)