Panther MCP Server

Instructions

Implementation Reference

• src/mcp_panther/panther_mcp_core/tools/alerts.py:509-575 (handler)

  The primary handler implementation for the 'add_alert_comment' MCP tool. This async function handles adding a comment to a Panther alert via the REST API /alert-comments endpoint. It includes input validation through Annotated types, error handling for 404/400 status codes, and returns a standardized success/error response. The @mcp_tool decorator also handles schema generation from Field descriptions and tool registration.

  @mcp_tool(
      annotations={
          "permissions": all_perms(Permission.ALERT_MODIFY),
          "destructiveHint": True,
      }
  )
  async def add_alert_comment(
      alert_id: Annotated[
          str,
          Field(min_length=1, description="The ID of the alert to comment on"),
      ],
      comment: Annotated[
          str,
          Field(min_length=1, description="The comment text to add"),
      ],
  ) -> dict[str, Any]:
      """Add a comment to a Panther alert. Comments support Markdown formatting.
  
      Returns:
          Dict containing:
          - success: Boolean indicating if the comment was added successfully
          - comment: Created comment information if successful
          - message: Error message if unsuccessful
      """
      logger.info(f"Adding comment to alert {alert_id}")
  
      try:
          # Prepare request body
          body = {
              "alertId": alert_id,
              "body": comment,
              "format": "PLAIN_TEXT",  # Default format
          }
  
          # Execute the REST API call
          async with get_rest_client() as client:
              comment_data, status = await client.post(
                  "/alert-comments", json_data=body, expected_codes=[200, 400, 404]
              )
  
          if status == 404:
              logger.error(f"Alert not found: {alert_id}")
              return {
                  "success": False,
                  "message": f"Alert not found: {alert_id}",
              }
  
          if status == 400:
              logger.error(f"Bad request when adding comment to alert {alert_id}")
              return {
                  "success": False,
                  "message": f"Bad request when adding comment to alert {alert_id}",
              }
  
          logger.info(f"Successfully added comment to alert {alert_id}")
  
          return {
              "success": True,
              "comment": comment_data,
          }
  
      except Exception as e:
          logger.error(f"Failed to add alert comment: {str(e)}")
          return {
              "success": False,
              "message": f"Failed to add alert comment: {str(e)}",
          }

• src/mcp_panther/panther_mcp_core/tools/alerts.py:509-514 (registration)

  The @mcp_tool decorator call that registers the add_alert_comment function in the MCP tool registry. Specifies required permissions (ALERT_MODIFY) and hints it as destructive.

  @mcp_tool(
      annotations={
          "permissions": all_perms(Permission.ALERT_MODIFY),
          "destructiveHint": True,
      }
  )

• src/mcp_panther/panther_mcp_core/tools/alerts.py:516-524 (schema)

  Input schema definition using Pydantic Annotated with Field validators and descriptions, which are used by the MCP framework to generate the tool's JSON schema for input validation.

      alert_id: Annotated[
          str,
          Field(min_length=1, description="The ID of the alert to comment on"),
      ],
      comment: Annotated[
          str,
          Field(min_length=1, description="The comment text to add"),
      ],
  ) -> dict[str, Any]: