send_notification

Instructions

Implementation Reference

• src/jons_mcp_pushover/tools/pushover.py:17-97 (handler)

  The primary handler function for the 'send_notification' tool. It validates inputs, retrieves credentials from environment variables, constructs the API request payload, sends an HTTP POST to the Pushover API using httpx, parses the response, and returns success details or raises errors.

  async def send_notification(
      message: str,
      title: str | None = None,
      url: str | None = None,
      url_title: str | None = None,
      priority: int = 0,
      sound: str | None = None,
  ) -> dict[str, str | int]:
      """Send a push notification via Pushover.
  
      Args:
          message: The notification message body (required).
          title: Title shown at top of notification. Defaults to app name.
          url: URL to include (tappable in notification).
          url_title: Label for the URL instead of showing raw URL.
          priority: Priority level from -2 (silent) to 2 (emergency). Default 0.
          sound: Notification sound name. See Pushover docs for available sounds.
  
      Returns:
          Dictionary with 'status' (1 for success) and 'request' (UUID string).
  
      Raises:
          ValueError: If priority is out of range or sound is invalid.
          PushoverError: If Pushover API returns an error or credentials are missing.
      """
      # Get credentials from environment
      api_token = os.environ.get("PUSHOVER_API_TOKEN")
      user_key = os.environ.get("PUSHOVER_USER_KEY")
  
      if not api_token:
          raise PushoverError("PUSHOVER_API_TOKEN environment variable is not set")
      if not user_key:
          raise PushoverError("PUSHOVER_USER_KEY environment variable is not set")
  
      # Validate priority
      if not PUSHOVER_PRIORITY_MIN <= priority <= PUSHOVER_PRIORITY_MAX:
          raise ValueError(
              f"Priority must be between {PUSHOVER_PRIORITY_MIN} and "
              f"{PUSHOVER_PRIORITY_MAX}, got {priority}"
          )
  
      # Validate sound if provided
      if sound is not None and sound not in PUSHOVER_VALID_SOUNDS:
          raise ValueError(
              f"Invalid sound '{sound}'. Valid sounds: {', '.join(PUSHOVER_VALID_SOUNDS)}"
          )
  
      # Build form data
      data: dict[str, str | int] = {
          "token": api_token,
          "user": user_key,
          "message": message,
      }
  
      if title is not None:
          data["title"] = title
      if url is not None:
          data["url"] = url
      if url_title is not None:
          data["url_title"] = url_title
      if priority != 0:
          data["priority"] = priority
      if sound is not None:
          data["sound"] = sound
  
      # Send request
      async with httpx.AsyncClient(timeout=REQUEST_TIMEOUT) as client:
          response = await client.post(PUSHOVER_API_URL, data=data)
  
      # Parse response
      result = response.json()
  
      if response.status_code != 200 or result.get("status") != 1:
          errors = result.get("errors", [])
          raise PushoverError(
              "Pushover API request failed",
              status_code=response.status_code,
              errors=errors,
          )
  
      return {"status": result["status"], "request": result["request"]}

• src/jons_mcp_pushover/server.py:52-52 (registration)

  The line where the send_notification tool is registered with the FastMCP server instance using mcp.tool().

  mcp.tool(send_notification)

• src/jons_mcp_pushover/server.py:12-12 (registration)

  Import of the send_notification tool into the server module from the tools package.

  from .tools import send_notification

• src/jons_mcp_pushover/tools/__init__.py:6-6 (registration)

  Export of send_notification in the tools package __all__ list, making it available for import.

  "send_notification",

• src/jons_mcp_pushover/tools/__init__.py:3-3 (registration)

  Import of the handler from pushover.py into the tools __init__.py for package-level access.

  from .pushover import send_notification